python-mkdocs-autorefs
Port variant v12
Summary Automatically link across pages in MkDocs (3.12)
Package version 1.4.2
Homepage https://mkdocstrings.github.io/autorefs
Keywords python
Maintainer Python Automaton
License Not yet specified
Other variants v13
Ravenports Buildsheet | History
Ravensource Port Directory | History
Last modified 24 MAY 2025, 21:07:17 UTC
Port created 01 JAN 2023, 17:21:46 UTC
Subpackage Descriptions
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)
Configuration Switches (platform-specific settings discarded)
PY312 ON Build using Python 3.12 PY313 OFF Build using Python 3.13
Package Dependencies by Type
Build (only) python312:dev:std
python-pip:single:v12
autoselect-python:single:std
Build and Runtime python312:primary:std
Runtime (only) python-Markdown:single:v12
python-MarkupSafe:single:v12
python-mkdocs:single:v12
Download groups
main mirror://PYPIWHL/87/dc/fc063b78f4b769d1956319351704e23ebeba1e9e1d6a41b4b602325fd7e4
Distribution File Information
83d6d777b66ec3c372a1aad4ae0cf77c243ba5bcda5bf0c6b8a2c5e7a3d89f13 24969 python-src/mkdocs_autorefs-1.4.2-py3-none-any.whl
Ports that require python-mkdocs-autorefs:v12
python-mkdocstrings-python-legacy:v12 Legacy Python handler for mkdocstrings (3.12)
python-mkdocstrings:v12 Documentation from sources for MkDocs (3.12)