python-mkdocs-autorefs
Port variant v11
Summary Automatically link across pages in MkDocs (3.11)
BROKEN
Package version 1.2.0
Homepage https://mkdocstrings.github.io/autorefs
Keywords python
Maintainer Python Automaton
License Not yet specified
Other variants v12
Ravenports Buildsheet | History
Ravensource Port Directory | History
Last modified 07 SEP 2024, 17:00:23 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 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. ### 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
Configuration Switches (platform-specific settings discarded)
PY311 ON Build using Python 3.11 PY312 OFF Build using Python 3.12
Package Dependencies by Type
Build (only) python-pip:single:v11
autoselect-python:single:std
Build and Runtime python311:single:std
Runtime (only) python-Markdown:single:v11
python-MarkupSafe:single:v11
python-mkdocs:single:v11
Download groups
main mirror://PYPIWHL/71/26/4d39d52ea2219604053a4d05b98e90d6a335511cc01806436ec4886b1028
Distribution File Information
d588754ae89bd0ced0c70c06f58566a4ee43471eeeee5202427da7de9ef85a2f 16522 mkdocs_autorefs-1.2.0-py3-none-any.whl
Ports that require python-mkdocs-autorefs:v11
python-mkdocstrings:v11 Documentation from sources for MkDocs (3.11)