| single |
# mkdocs-autorefs
[ci]
[documentation]
[pypi version]
[conda version]
[gitpod]
[gitter]
Automatically link across pages in MkDocs.
## Installation
```bash
pip install mkdocs-autorefs
```
## Usage
```yaml
# mkdocs.yml
plugins:
- search
- autorefs
```
In one of your Markdown files (e.g. `doc1.md`) create some headings:
```markdown
## Hello, world!
## Another heading
Link to [Hello, World!] on the same page.
```
This is a [*normal* link to an anchor]. MkDocs generates anchors for each
heading, and they can always be used to link to something, either within
the same page (as shown here) or by specifying the path of the other page.
But with this plugin, you can **link to a heading from any other page** on
the site *without* needing to know the path of either of the pages, just
the heading title itself.
Let's create another Markdown page to try this, `subdir/doc2.md`:
```markdown
We can [link to that heading][hello-world] from another page too.
This works the same as [a normal link to that heading].
```
Linking to a heading without needing to know the destination page can be
useful if specifying that path is cumbersome, e.g. when the pages have
deeply nested paths, are far apart, or are moved around frequently.
### Non-unique headings
When linking to a heading that appears several times throughout the site,
this plugin will log a warning message stating that multiple URLs were
found and that headings should be made unique, and will resolve the link
using the first found URL.
To prevent getting warnings, use [Markdown anchors] to add unique aliases
to your headings, and use these aliases when referencing the headings.
If you cannot use Markdown anchors, for example because you inject the same
generated contents in multiple locations (for example mkdocstrings' API
documentation), then you can try to alleviate the warnings by enabling the
`resolve_closest` option:
```yaml
plugins:
- autorefs:
resolve_closest: true
```
When `resolve_closest` is enabled, and multiple URLs are found for the same
identifier, the plugin will try to resolve to the one that is "closest" to
the current page (the page containing the link). By closest, we mean:
- URLs that are relative to the current page's URL, climbing up parents
- if multiple URLs are relative to it, use the one at the shortest distance
if possible.
If multiple relative URLs are at the same distance, the first of these URLs
will be used. If no URL is relative to the current page's URL, the first
URL of all found URLs will be used.
Examples:
Current page | Candidate URLs | Relative URLs | Winner
------------ | -------------- | ------------- | ------
` ` | `x/#b`, `#b` | `#b` | `#b` (only one relative)
`a/` | `b/c/#d`, `c/#d` | none | `b/c/#d` (no relative, use first one, even
if longer distance)
`a/b/` | `x/#e`, `a/c/#e`, `a/d/#e` | `a/c/#e`, `a/d/#e` (relative to
parent `a/`) | `a/c/#e` (same distance, use first one)
`a/b/` | `x/#e`, `a/c/d/#e`, `a/c/#e` | `a/c/d/#e`, `a/c/#e` (relative to
parent `a/`) | `a/c/#e` (shortest distance)
`a/b/c/` | `x/#e`, `a/#e`, `a/b/#e`, `a/b/c/d/#e`, `a/b/c/#e` |
|