mkdocs-autorefs

What it is and what it does

mkdocs-autorefs is a MkDocs plugin that extends the documentation linking model by allowing you to reference headings and anchors by their title alone, without needing to know or specify the file path of the target page. Normally in MkDocs you must write explicit relative or absolute paths to link between pages; this plugin indexes all headings and custom anchors across your site and resolves reference-style links like `[text][heading-name]` to the correct destination automatically.

The plugin handles several real-world complications: when the same heading appears on multiple pages, it logs a warning and uses the first match, or you can enable `resolve_closest` to pick the heading nearest to the current page. It supports custom Markdown anchors using the `attr_list` extension syntax, allowing you to create unique aliases for headings and link to them from anywhere. It also integrates with Material for MkDocs' instant preview feature by conditionally setting link title attributes. The plugin requires Python 3.9 or later and depends on Markdown, markupsafe, and mkdocs.

Use it for

• Link to API documentation headings from multiple pages without hardcoding relative paths that break when pages move.
• Create stable reference aliases for headings that appear in multiple OS-specific or version-specific documentation pages.
• Build documentation that references generated API docs (e.g., from mkdocstrings) by heading name rather than computed file paths.
• Simplify cross-references in large documentation sites where page structure is nested or frequently reorganized.
• Add custom anchor points in the middle of documents and reference them from anywhere without knowing the source file location.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

mkdocs-autorefs on PyPI

Before you install

Low friction install with a pure-Python wheel. Maintenance status is aging—last release was 185 days ago—but the repository remains active with no archived flag and recent commits as of 2026-02-10.

Requires MkDocs to be installed and configured; the attr_list Markdown extension must be enabled to use Markdown anchors feature.

License in practice

ISC license is permissive, allowing commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

pip install mkdocs-autorefs

# In mkdocs.yml:
plugins:
  - search
  - autorefs

# In doc1.md:
## Hello, world!

# In doc2.md:
We can [link to that heading][hello-world] from another page too.

Package facts

Evidence: mkdocs_autorefs-1.4.4-py3-none-any.whl

Tags

More Software Development packages

See also mkdocs-htmlproofer-plugin · mkdocs-include-markdown-plugin · mkdocstrings · mkdocs-redirects · mkdocs-auto-tag-plugin · mkdocs-click · mkdocs-with-pdf · mkdocs-gen-files · mike · sphinx-hoverxref