Skip to content

feature: add style for mkdocstrings backlinks - #239

Merged
squidfunk merged 1 commit into
masterfrom
feature/autorefs-backlinks
Sep 25, 2026
Merged

squidfunk merged 1 commit into
masterfrom
feature/autorefs-backlinks

Conversation

@pawamoy

@pawamoy pawamoy commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Styles for zensical/zensical#964.

We can also consider adding these styles for tree-style backlinks:

/* Tree-like output for backlinks. */
.doc-backlink-list {
  --tree-clr: var(--md-default-fg-color);
  --tree-font-size: 1rem;
  --tree-item-height: 1;
  --tree-offset: 1rem;
  --tree-thickness: 1px;
  --tree-style: solid;
  display: grid;
  list-style: none !important;
}

.doc-backlink-list li > span:first-child {
  text-indent: .3rem;
}
.doc-backlink-list li {
  padding-inline-start: var(--tree-offset);
  border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr);
  position: relative;
  margin-left: 0 !important;

  &:last-child {
    border-color: transparent;
  }
  &::before{
    content: '';
    position: absolute;
    top: calc(var(--tree-item-height) / 2 * -1 * var(--tree-font-size) + var(--tree-thickness));
    left: calc(var(--tree-thickness) * -1);
    width: calc(var(--tree-offset) + var(--tree-thickness) * 2);
    height: calc(var(--tree-item-height)  * var(--tree-font-size));
    border-left: var(--tree-thickness) var(--tree-style) var(--tree-clr);
    border-bottom: var(--tree-thickness) var(--tree-style) var(--tree-clr);
  }
  &::after{
    content: '';
    position: absolute;
    border-radius: 50%;
    background-color: var(--tree-clr);
    top: calc(var(--tree-item-height) / 2 * 1rem);
    left: var(--tree-offset) ;
    translate: calc(var(--tree-thickness) * -1) calc(var(--tree-thickness) * -1);
  }
}

That's what gives a style similar to the output of the tree command:

% tree -L2
.
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── config
│   ├── coverage.ini
│   ├── git-changelog.toml
│   ├── pytest.ini
│   ├── ruff.toml
│   ├── ty.toml
│   └── vscode
├── CONTRIBUTING.md
[...]

Otherwise backlinks are just rendered as bullet points.

This CSS wasn't part of autorefs/mkdocstrings previously, so not sure if we should make it the default.

Signed-off-by: Timothée Mazzucotelli <dev@pawamoy.fr>

@squidfunk squidfunk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes look good! Regarding tree-style backlinks I trust your judgment.

@squidfunk
squidfunk merged commit a406071 into master Sep 25, 2026
4 checks passed
@squidfunk
squidfunk deleted the feature/autorefs-backlinks branch September 25, 2026 14:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants