--- id: mkdocs-autorefs version: "1.4.4" license: ISC license_treatment: permissive maintenance: aging --- # mkdocs-autorefs — Automatically link across pages in MkDocs. License: permissive · Maintenance: aging · Downloads: 8.1M/mo ## 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 above — 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 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 - License: ISC (permissive) - Python support: supports_current - Install friction: low - Maintenance: aging - Downloads: 8.1M/month (top 5,000 on PyPI) - Known vulnerabilities: none known ## Tags mkdocs cross-page linking, automatic heading references, mkdocs anchor linking, documentation cross-references, mkdocs link resolution, heading aliases markdown, mkdocs internal links, mkdocs-plugin, documentation-linking, cross-references [View on SkillFed](https://skillfed.io/packages/mkdocs-autorefs) · [View on PyPI](https://pypi.org/project/mkdocs-autorefs/)