autorefs

mkdocs-autorefs is a MkDocs plugin that lets you link to a heading or anchor anywhere on a documentation site without knowing that page’s path. Instead of hardcoding relative links that break when files move, authors write [Some heading][heading-id] and autorefs resolves it to the right URL once the whole site has been rendered, using either the heading’s slugified title or an explicit Markdown anchor ([](){ #id }).

Beyond simple links, the plugin supports a resolve_closest mode for disambiguating identifiers that appear on multiple pages (picking the URL nearest the linking page), configurable link titles/tooltips, and an opt-in backlinks system that lets other plugins record and later render “referenced by” lists. It was built as the cross-referencing engine underneath mkdocstrings, but works standalone in any MkDocs site.

What You Get

• Path-free cross-references - link to any heading via [text][identifier] instead of a relative file path that breaks when pages move
• Markdown anchors - drop an [](){ #id } anchor anywhere in a document and link to it directly, independent of heading text
• resolve_closest disambiguation - when an identifier appears on multiple pages, autorefs picks the URL structurally closest to the linking page
• Configurable link titles - link_titles controls whether hover tooltips are added, with an auto mode that detects Material for MkDocs’ instant-preview feature and avoids conflicting with it
• Backlinks API - record_backlinks plus get_backlinks() let consuming plugins render “referenced by” sections from cross-reference data collected during the build

Common Use Cases

• Cross-linking API docs - mkdocstrings uses autorefs internally so generated API reference pages can link to each other by fully qualified name
• Large multi-page documentation sites - avoid maintaining relative paths across deeply nested doc trees that get reorganized often
• Stable anchors for shared content - use Markdown anchors to give unique, linkable aliases to headings that repeat across pages (e.g. “Installation” sections per OS)
• Building “referenced by” navigation - other plugins or on_env hooks can query recorded backlinks to render reverse-reference lists on a page

Under The Hood

Architecture The plugin follows MkDocs’ standard plugin/event-hook architecture (a BasePlugin subclass wiring on_config, on_page_markdown, and on_env), with responsibilities split across three internal modules: _internal/plugin.py (the AutorefsPlugin itself, tracking primary/secondary/absolute URL maps for identifier resolution), _internal/references.py (the Markdown extension and its inline/tree processors that recognize [text][id] syntax and scan headings/anchors), and _internal/backlinks.py (the backlink-recording data structures). Data flows one-way through the MkDocs render pipeline: anchors are collected into maps as each page’s Markdown converts to HTML, then a final on_env pass walks every rendered page resolving pending references against those maps, with resolve_closest doing breadcrumb-distance comparisons for ambiguous multi-page matches. The public surface is deliberately curated through mkdocs_autorefs/__init__.py, and the legacy mkdocs_autorefs.plugin import path is kept alive only as a lazy deprecated shim — a disciplined, low-breakage migration pattern for downstream consumers like mkdocstrings.

Tech Stack Built with pdm-backend and dynamic versioning via a custom version-getter script. Runtime dependencies are intentionally minimal: Markdown, markupsafe, and mkdocs itself, reflecting its role as a thin plugin rather than a standalone tool. It registers through the standard mkdocs.plugins entry-point group so any MkDocs install can discover it just by declaring autorefs in mkdocs.yml. Dev tooling includes ruff for linting, ty for type checking, and a pytest/pytest-cov/pytest-xdist/pytest-randomly stack for tests; the project supports Python 3.10 through 3.14 and ships to both PyPI and conda-forge.

Code Quality The test suite is substantial relative to source size, covering plugin URL registration, backlink recording, the public API surface, and the Markdown reference syntax across dedicated test files, with clear per-test docstrings and explicit pytest.raises assertions for error paths. CI runs a quality matrix across multiple operating systems and Python versions. The codebase is typed throughout (from __future__ import annotations, TYPE_CHECKING-gated imports, a Typing :: Typed classifier) and checked with a modern type checker. Deprecated code paths are explicitly flagged with scheduled-removal markers rather than left to accumulate as silent cruft.

API Design The public import surface is a single, deliberately curated __all__ list; the old mkdocs_autorefs.plugin module path still works but only as a lazy shim that emits a DeprecationWarning, letting consumers migrate on their own schedule. Zero configuration is required to get started — declaring autorefs as a plugin is enough — while power users get well-documented YAML options (resolve_closest, link_titles, strip_title_tags) each explained inline with examples and, for the trickiest one, a worked resolution table in the README. The backlinks API returns structured Backlink/BacklinkCrumb objects instead of raw tuples, keeping the integration contract for downstream plugins explicit.