| Name | mkdocs-autorefs JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | |
| Summary | Automatically link across pages in MkDocs. |
| upload_time | 2024-02-29 15:52:19 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | ISC |
| keywords |
mkdocs
mkdocs-plugin
docstrings
autodoc
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mkdocs-autorefs
[](https://github.com/mkdocstrings/autorefs/actions?query=workflow%3Aci)
[](https://mkdocstrings.github.io/autorefs/)
[](https://pypi.org/project/mkdocs-autorefs/)
[](https://anaconda.org/conda-forge/mkdocs-autorefs)
[](https://gitpod.io/#https://github.com/mkdocstrings/autorefs)
[](https://app.gitter.im/#/room/#autorefs:gitter.im)
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!](#hello-world) on the same page.
```
This is a [*normal* link to an anchor](https://www.mkdocs.org/user-guide/writing-your-docs/#linking-to-pages). 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](../doc1.md#hello-world).
```
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](https://github.com/mkdocs/mkdocs/issues/1592).
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](#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, `[]()`, except both the text value and URL of the link are empty. Then we see `{#id-of-the-anchor}`, which is the syntax supported by the [`attr_list`](https://python-markdown.github.io/extensions/attr_list/) 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 `<a id="foo"></a>` 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}
Paragraph about foobar.
```
...making it possible to link to this anchor with our automatic links:
```md
In any document.
Check out the [paragraph about foobar][foobar-pararaph].
```
If you add a Markdown anchor right above a heading, this anchor will redirect to the heading itself:
```md
[](){#foobar}
## A verbose title about foobar
```
Linking to the `foobar` anchor will bring you directly to the heading, not the anchor itself, so the URL will show `#a-verbose-title-about-foobar` instead of `#foobar`. These anchors therefore act as "aliases" for headings. It is possible to define multiple aliases per heading:
```md
[](){#contributing}
[](){#development-setup}
## How to contribute to the project?
```
Such aliases are especially useful when the same headings appear in several different pages. Without aliases, linking to the heading is undefined behavior (it could lead to any one of the headings). With unique aliases above headings, you can make sure to link to the right heading.
For example, consider the following setup. You have one document per operating system describing how to install a project with the OS package manager or from sources:
```tree
docs/
install/
arch.md
debian.md
gentoo.md
```
Each page has:
```md
## Install with package manager
...
## Install from sources
...
```
You don't want to change headings and make them redundant, like `## Arch: Install with package manager` and `## Debian: Install with package manager` just to be able to reference the right one with autorefs. Instead you can do this:
```md
[](){#arch-install-pkg}
## Install with package manager
...
[](){#arch-install-src}
## Install from sources
...
```
...changing `arch` by `debian`, `gentoo`, etc. in the other pages.
Raw data
{
"_id": null,
"home_page": "",
"name": "mkdocs-autorefs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "mkdocs mkdocs-plugin docstrings autodoc",
"author": "",
"author_email": "Oleh Prypin <oleh@pryp.in>, Timoth\u00e9e Mazzucotelli <dev@pawamoy.fr>",
"download_url": "https://files.pythonhosted.org/packages/ce/75/0ced93354fd9df40531c548f07d6462912eea9519e8cd78a8e6b42d73c4a/mkdocs_autorefs-1.0.1.tar.gz",
"platform": null,
"description": "# mkdocs-autorefs\n\n[](https://github.com/mkdocstrings/autorefs/actions?query=workflow%3Aci)\n[](https://mkdocstrings.github.io/autorefs/)\n[](https://pypi.org/project/mkdocs-autorefs/)\n[](https://anaconda.org/conda-forge/mkdocs-autorefs)\n[](https://gitpod.io/#https://github.com/mkdocstrings/autorefs)\n[](https://app.gitter.im/#/room/#autorefs:gitter.im)\n\nAutomatically link across pages in MkDocs.\n\n## Installation\n\nWith `pip`:\n\n```bash\npython3 -m pip install mkdocs-autorefs\n```\n\n## Usage\n\n```yaml\n# mkdocs.yml\nplugins:\n - search\n - autorefs\n```\n\nIn one of your Markdown files (e.g. `doc1.md`) create some headings:\n\n```markdown\n## Hello, world!\n\n## Another heading\n\nLink to [Hello, World!](#hello-world) on the same page.\n```\n\nThis is a [*normal* link to an anchor](https://www.mkdocs.org/user-guide/writing-your-docs/#linking-to-pages). 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.\n\nBut 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. \nLet's create another Markdown page to try this, `subdir/doc2.md`:\n\n```markdown\nWe can [link to that heading][hello-world] from another page too.\n\nThis works the same as [a normal link to that heading](../doc1.md#hello-world).\n```\n\nLinking 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](https://github.com/mkdocs/mkdocs/issues/1592).\n\nNote 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](#markdown-anchors) to add unique aliases to your headings.\n\n### Markdown anchors\n\nThe autorefs plugin offers a feature called \"Markdown anchors\". Such anchors can be added anywhere in a document, and linked to from any other place.\n\nThe syntax is:\n\n```md\n[](){#id-of-the-anchor}\n```\n\nIf you look closely, it starts with the usual syntax for a link, `[]()`, except both the text value and URL of the link are empty. Then we see `{#id-of-the-anchor}`, which is the syntax supported by the [`attr_list`](https://python-markdown.github.io/extensions/attr_list/) 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 `<a id=\"foo\"></a>` are not supported.\n\nThe `attr_list` extension must be enabled for the Markdown anchors feature to work:\n\n```yaml\n# mkdocs.yml\nplugins:\n - search\n - autorefs\n\nmarkdown_extensions:\n - attr_list\n```\n\nNow, you can add anchors to documents:\n\n```md\nSomewhere in a document.\n\n[](){#foobar-paragraph}\n\nParagraph about foobar.\n```\n\n...making it possible to link to this anchor with our automatic links:\n\n```md\nIn any document.\n\nCheck out the [paragraph about foobar][foobar-pararaph].\n```\n\nIf you add a Markdown anchor right above a heading, this anchor will redirect to the heading itself:\n\n```md\n[](){#foobar}\n## A verbose title about foobar\n```\n\nLinking to the `foobar` anchor will bring you directly to the heading, not the anchor itself, so the URL will show `#a-verbose-title-about-foobar` instead of `#foobar`. These anchors therefore act as \"aliases\" for headings. It is possible to define multiple aliases per heading:\n\n```md\n[](){#contributing}\n[](){#development-setup}\n## How to contribute to the project?\n```\n\nSuch aliases are especially useful when the same headings appear in several different pages. Without aliases, linking to the heading is undefined behavior (it could lead to any one of the headings). With unique aliases above headings, you can make sure to link to the right heading.\n\nFor example, consider the following setup. You have one document per operating system describing how to install a project with the OS package manager or from sources:\n\n```tree\ndocs/\n install/\n arch.md\n debian.md\n gentoo.md\n```\n\nEach page has:\n\n```md\n## Install with package manager\n...\n\n## Install from sources\n...\n```\n\nYou don't want to change headings and make them redundant, like `## Arch: Install with package manager` and `## Debian: Install with package manager` just to be able to reference the right one with autorefs. Instead you can do this:\n\n```md\n[](){#arch-install-pkg}\n## Install with package manager\n...\n\n[](){#arch-install-src}\n## Install from sources\n...\n```\n\n...changing `arch` by `debian`, `gentoo`, etc. in the other pages.\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "Automatically link across pages in MkDocs.",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://mkdocstrings.github.io/autorefs/changelog",
"Discussions": "https://github.com/mkdocstrings/autorefs/discussions",
"Documentation": "https://mkdocstrings.github.io/autorefs",
"Gitter": "https://gitter.im/mkdocstrings/autorefs",
"Homepage": "https://mkdocstrings.github.io/autorefs",
"Issues": "https://github.com/mkdocstrings/autorefs/issues",
"Repository": "https://github.com/mkdocstrings/autorefs"
},
"split_keywords": [
"mkdocs",
"mkdocs-plugin",
"docstrings",
"autodoc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f601d413c98335ed75d8c211afb91320811366d55fb0ef7f4b01b9ab19630eac",
"md5": "1665bfa337c1803de27f61d557e1f8cd",
"sha256": "aacdfae1ab197780fb7a2dac92ad8a3d8f7ca8049a9cbe56a4218cd52e8da570"
},
"downloads": -1,
"filename": "mkdocs_autorefs-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1665bfa337c1803de27f61d557e1f8cd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13444,
"upload_time": "2024-02-29T15:51:52",
"upload_time_iso_8601": "2024-02-29T15:51:52.989901Z",
"url": "https://files.pythonhosted.org/packages/f6/01/d413c98335ed75d8c211afb91320811366d55fb0ef7f4b01b9ab19630eac/mkdocs_autorefs-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce750ced93354fd9df40531c548f07d6462912eea9519e8cd78a8e6b42d73c4a",
"md5": "6a91f692e94f040a8a27b94eef17184e",
"sha256": "f684edf847eced40b570b57846b15f0bf57fb93ac2c510450775dcf16accb971"
},
"downloads": -1,
"filename": "mkdocs_autorefs-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6a91f692e94f040a8a27b94eef17184e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17743,
"upload_time": "2024-02-29T15:52:19",
"upload_time_iso_8601": "2024-02-29T15:52:19.753436Z",
"url": "https://files.pythonhosted.org/packages/ce/75/0ced93354fd9df40531c548f07d6462912eea9519e8cd78a8e6b42d73c4a/mkdocs_autorefs-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-29 15:52:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mkdocstrings",
"github_project": "autorefs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-autorefs"
}
