| single |
# mkdocs-autorefs
[ci]
[documentation]
[pypi version]
[conda version]
[gitpod]
[gitter]
Automatically link across pages in MkDocs.
## Installation
With `pip`:
```bash
python3 -m 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. And the
issue is somewhat exacerbated by the fact that [MkDocs supports only
*relative* links between pages].
Note that this plugin's behavior is undefined when trying to link to a
heading title that appears several times throughout the site. Currently it
arbitrarily chooses one of the pages. In such cases, use [Markdown anchors]
to add unique aliases to your headings.
### Markdown anchors
The autorefs plugin offers a feature called "Markdown anchors". Such
anchors can be added anywhere in a document, and linked to from any other
place.
The syntax is:
```md
[](){#id-of-the-anchor}
```
If you look closely, it starts with the usual syntax for a link, `[]
extension. It sets an HTML id to the anchor element. The autorefs plugin
simply gives a meaning to such anchors with ids. Note that raw HTML anchors
like `` are not supported.
The `attr_list` extension must be enabled for the Markdown anchors feature
to work:
```yaml
# mkdocs.yml
plugins:
- search
- autorefs
markdown_extensions:
- attr_list
```
Now, you can add anchors to documents:
```md
Somewhere in a document.
[](){#foobar-paragraph}
|