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

A MkDocs plugin that automatically creates cross-page links to headings and anchors by reference name, without requiring you to know or specify the destination page path.

Yes, if you use MkDocs and need to create cross-page links without managing explicit file paths. The plugin is stable (Development Status Beta), has no known vulnerabilities, and low install friction. The aging maintenance status (185 days since last release) is not a blocker for a mature plugin with a clear, focused scope, but verify it works with your MkDocs version before relying on it for production documentation.

Install

mkdocs-autorefs on PyPI

pip install mkdocs-autorefs

uv add mkdocs-autorefs

poetry add mkdocs-autorefs

Installing mkdocs-autorefs

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.

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.

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

Verify before relying

• Performance impact when resolving links across very large documentation sites with hundreds of pages.
• Behavior when heading titles contain special characters or non-ASCII text that may affect slug generation.

Package facts

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

Keywords: mkdocs, mkdocs-plugin, docstrings, autodoc

Tags

More Software Development packages