# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-mkdocs-autorefs
VERSION=		1.4.4
KEYWORDS=		python
VARIANTS=		v13 v14
SDESC[v13]=		Automatically link across pages in MkDocs (3.13)
SDESC[v14]=		Automatically link across pages in MkDocs (3.14)
HOMEPAGE=		https://mkdocstrings.github.io/autorefs
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/28/de/a3e710469772c6a89595fc52816da05c1e164b4c866a89e3cb82fb1b67c5
DISTFILE[1]=		mkdocs_autorefs-1.4.4-py3-none-any.whl:main
DIST_SUBDIR=		python-src
DF_INDEX=		1
SPKGS[v13]=		single
SPKGS[v14]=		single

OPTIONS_AVAILABLE=	PY313 PY314
OPTIONS_STANDARD=	none
VOPTS[v13]=		PY313=ON PY314=OFF
VOPTS[v14]=		PY313=OFF PY314=ON

DISTNAME=		mkdocs_autorefs-1.4.4.dist-info

GENERATED=		yes

[PY313].RUN_DEPENDS_ON=			python-Markdown:single:v13
					python-MarkupSafe:single:v13
					python-mkdocs:single:v13
[PY313].USES_ON=			python:v13,wheel

[PY314].RUN_DEPENDS_ON=			python-Markdown:single:v14
					python-MarkupSafe:single:v14
					python-mkdocs:single:v14
[PY314].USES_ON=			python:v14,wheel

[FILE:3247:descriptions/desc.single]
# mkdocs-autorefs

[ci]
[documentation]
[pypi version]
[conda version]
[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.

TIP: **Finding the anchor of a heading.** To find the anchor for a specific
heading, the easiest way is to serve your docs, go to that heading, click
its permalink if there's one, and copy the anchor from the browser URL bar.
If the heading doesn't have a permalink, the anchor can be retrieved from
the HTML directly (by inspecting the source of the page): it's the `id`
attribute of the heading. Generally though, anchors are generated from
heading titles by "slugifying" them, i.e. transforming them to lowercase,
removing special characters, and replacing spaces with dashes. For example
a heading like ``## Hello *World* (and 2 other `things`)`` will be
slugified to `hello-world-and-2-other-things`.

### 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:


[FILE:128:distinfo]
834ef5408d827071ad1bc69e0f39704fa34c7fc05bc8e1c72b227dfdc5c76089        25530 python-src/mkdocs_autorefs-1.4.4-py3-none-any.whl