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

NAMEBASE=		python-mkdocs-autorefs
VERSION=		1.4.3
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/9f/4d/7123b6fa2278000688ebd338e2a06d16870aaf9eceae6ba047ea05f92df1
DISTFILE[1]=		mkdocs_autorefs-1.4.3-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.3.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:3107: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.

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


[FILE:128:distinfo]
469d85eb3114801d08e9cc55d102b3ba65917a869b893403b8987b601cf55dc9        25034 python-src/mkdocs_autorefs-1.4.3-py3-none-any.whl