mkdocs-autorefs

1.4.4 · active · verified Sat Apr 11

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.

Common errors

```
ERROR - Config value 'plugins': The "autorefs" plugin is not installed.
```
cause The 'mkdocs-autorefs' package is installed in your Python environment but has not been enabled in your MkDocs configuration file (`mkdocs.yml`).

fix Add `autorefs` to the `plugins` section in your `mkdocs.yml` file: ```yaml plugins: - search - autorefs ```
```
Multiple URLs found for 'x.y.z': ['reference/x/y/z/#x.y.z', 'user-guide/x/y/z#x.y.z']. Make sure to use unique headings, identifiers, or Markdown anchors (see our docs).
```
cause This warning occurs when the same heading title or identifier is used on multiple pages, making it ambiguous for `mkdocs-autorefs` to determine the correct link target. If 'strict' mode is enabled, this will halt the build.

fix Ensure all headings and Markdown anchors have unique identifiers across your documentation. Alternatively, use Markdown anchors with explicit IDs (e.g., `[]{#unique-id}` ) and reference those, or enable the `resolve_closest` option in the plugin's configuration to automatically resolve to the nearest link.
```
WARNING - reference/cli.md: Could not find cross-reference target '[answers_file]'
```
cause The `[text][identifier]` syntax is used, but `mkdocs-autorefs` cannot find a corresponding heading or Markdown anchor matching 'answers_file' anywhere in the documentation. This can be due to a typo, the target not existing, or the plugin not being properly configured.

fix Verify that the `identifier` within your `[text][identifier]` link exactly matches an existing heading (e.g., `## Answers File`) or a Markdown anchor (e.g., `[]{#answers_file}`). Ensure `mkdocs-autorefs` is correctly listed in your `mkdocs.yml` plugins section.
```
AttributeError: 'dict' object has no attribute 'link_titles'
```
cause This error typically arises when a custom `on_config` hook or an older version of `mkdocs-autorefs` attempts to access a plugin configuration option, like `link_titles`, in an incorrect or incompatible way, especially after a version upgrade.

fix Update `mkdocs-autorefs` to the latest version. If using custom plugin hooks, ensure they correctly access plugin options (e.g., `config.plugins['autorefs'].options['link_titles']`) and are compatible with the installed plugin version.

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.
gotcha The test script appears to be executing an MkDocs configuration file (e.g., `mkdocs.yml`) directly as a Python script, leading to a `SyntaxError`. MkDocs configuration files are YAML, not Python.
Fix: Ensure that your MkDocs configuration file is correctly processed by the `mkdocs` command (e.g., `mkdocs build`, `mkdocs serve`) and not executed directly by the Python interpreter.

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 →