Skip to main content

Automatically link across pages in MkDocs.

Project description

mkdocs-autorefs

ci documentation pypi version conda version gitpod gitter

Automatically link across pages in MkDocs.

Installation

With pip:

python3 -m pip install mkdocs-autorefs

Usage

# mkdocs.yml
plugins:
  - search
  - autorefs

In one of your Markdown files (e.g. doc1.md) create some headings:

## Hello, world!

## Another heading

Link to [Hello, World!](#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:

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.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_autorefs-0.5.0.tar.gz (12.5 kB view details)

Uploaded Source

Built Distribution

mkdocs_autorefs-0.5.0-py3-none-any.whl (9.6 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs_autorefs-0.5.0.tar.gz.

File metadata

  • Download URL: mkdocs_autorefs-0.5.0.tar.gz
  • Upload date:
  • Size: 12.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for mkdocs_autorefs-0.5.0.tar.gz
Algorithm Hash digest
SHA256 9a5054a94c08d28855cfab967ada10ed5be76e2bfad642302a610b252c3274c0
MD5 655e957154e45066f76c69b56db60557
BLAKE2b-256 0a0500bb9981e8e9ea4327197180c96953a6818ab1001e91beac6c192ad45cb8

See more details on using hashes here.

File details

Details for the file mkdocs_autorefs-0.5.0-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_autorefs-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7930fcb8ac1249f10e683967aeaddc0af49d90702af111a5e390e8b20b3d97ff
MD5 71d6a168dcfde5a75b1c0f214407b626
BLAKE2b-256 215ffe501daf6f06b93d5d9dff4319c04ad6e74965348dff22465bdd53e5e2d9

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page