mkdocs-autorefs

1.4.4 · active · verified Thu Apr 09

mkdocs-autorefs is an MkDocs plugin that automatically creates hyperlinks across pages and to specific sections within your documentation using a simple `[text][identifier]` syntax. It is currently at version 1.4.4 and is actively maintained with frequent, minor updates.

Warnings

breaking Support for Python 3.8 was dropped in version 1.3.0. Projects using mkdocs-autorefs on Python 3.8 will fail to install or run.
Fix: Upgrade your Python environment to 3.9 or higher, or explicitly pin `mkdocs-autorefs<1.3.0` in your dependencies.
deprecated Internal constants and classes (`AUTO_REF_RE`, `AutoRefInlineProcessor`) were renamed in version 1.1.0 to `AUTOREF_RE` and `AutorefsInlineProcessor` respectively. Direct programmatic usage of the old names will break.
Fix: Update any code directly referencing these internal symbols to use their new names: `AUTOREF_RE` and `AutorefsInlineProcessor`.
gotcha Older versions (prior to 1.0.1) had compatibility issues with `MkDocsConfig` on MkDocs 1.3 and earlier. This could lead to build failures.
Fix: Ensure you are using `mkdocs-autorefs` version 1.0.1 or newer. It is generally recommended to use MkDocs 1.4+ for full compatibility and access to the latest features.

Install

pip install mkdocs-autorefs Install stable version

Imports

AutorefsPlugin
```
from mkdocs_autorefs.plugin import AutorefsPlugin
```
This import is typically only used for programmatic interaction with the plugin. Most users configure mkdocs-autorefs directly in their `mkdocs.yml` file.

Quickstart

Add `autorefs` to the `plugins` section of your `mkdocs.yml`. Once configured, you can use the `[text][identifier]` syntax in your Markdown files. The identifier can be a page path (e.g., `index.md`) or a page path combined with a section heading (e.g., `page.md#section-heading`).

site_name: My Docs

plugins:
  - search
  - autorefs:
      enabled: true # Optional, default is true
      deduplicate_references: true # Optional, default is true

# Example Markdown usage (e.g., in a file `docs/api.md`):
# Link to another page: [Introduction][index.md]
# Link to a section: [Installation steps][setup.md#installation]

view raw JSON →