Skip to main content

MkDocs resolve absolute URLs Plugin

A MkDocs plugin that resolves absolute URLs relative to a configurable root url, with support for multi-version and multi-locale documentation sites based on the configurable url versioning scheme. Currently this only supports websites hosted through Read the Docs.

Overview

Why do I need this

Mkdocs doesn't natively support absolute links (reference). In addition, when using documentation with multiple versions or locales (for example on ReadtheDocs), absolute URLs like /docs/guide.html become problematic. This plugin:

  • Automatically prepends the absolute URLs in your Markdown files with the correct root URL
  • Falls back to the READTHEDOCS_CANONICAL_URL environment variable when no root_url is configured
  • Supports linking to specific locales or versions using a simple syntax, keeping the current locale/version (if present) when they are not inlcuded in the absolute link

How it works

Basic URL resolution

The plugin resolves absolute URLs by prepending a root URL (either from your config or from the Read the Docs environment):

Absolute URL Root URL Result
/bar/foo.png https://mywebsite.com https://mywebsite.com/bar/foo.png
/bar/foo.png https://mywebsite.com/subpage/ https://mywebsite.com/subpage/bar/foo.png

If the root URL is not configured, it is taken from the READTHEDOCS_CANONICAL_URL environment variable.

Cross-locale and cross-version urls

For sites that enable multiple locales and/or multiple versions, you can add the url_versioning_scheme option and use an extended URL syntax to link to specific versions or locales:

URL Format: /!<locale>/@<version>/<link>

  • !<locale>: Optional locale override to switch to a specific locale. Must be used with url_versioning_scheme set to multiple_versions_with_translations
  • @<version>: Optional version override to switch to a specific version. Must be used with url_versioning_scheme set to either multiple_versions_with_translations or multiple_versions_without_translations
  • Omit both to use the current locale/version (if present)

Examples

Given a root URL https://mywebsite.com, url versioning scheme multiple_versions_with_translations, current locale en, and current version latest:

URL Resolves to
/my/page https://mywebsite.com/en/latest/my/page (current locale & version)
/!fr/my/page https://mywebsite.com/fr/latest/my/page (locale override)
/@v2.0/my/page https://mywebsite.com/en/v2.0/my/page (version override)
/!fr/@v2.0/my/page https://mywebsite.com/fr/v2.0/my/page (locale and version override)

Configuration options

Option Description Default
root_url Root URL to prepend resolved URLs to READTHEDOCS_CANONICAL_URL environment variable
attributes HTML attributes containing the URLs to process ["href", "src", "data"]
prefix URL prefix to identify absolute URLs for processing /

Usage examples

Basic setup

plugins:
  - resolve-absolute-urls

With custom settings

plugins:
  - resolve-absolute-urls:
      root_url: https://mywebsite.io/
      attributes:
        - href
        - data-url
      prefix: /abs/
      url_versioning_scheme: multiple_versions_without_translations

License

This plugin is licensed under the CC-BY 4.0 license.

Acknowledgements

This project builds on work from OctoPrint/mkdocs-site-urls. We thank the original authors for their contributions and for publishing their work under an open license.

Metadata

Release files for mkdocs-resolve-absolute-urls-plugin 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mkdocs-resolve-absolute-urls-plugin 2.0.1
File Size Uploaded Provenance Actions
mkdocs_resolve_absolute_urls_plugin-2.0.1.tar.gz 10.6 kB Without provenance Details for mkdocs_resolve_absolute_urls_plugin-2.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mkdocs-resolve-absolute-urls-plugin 2.0.1
File Interpreter ABI Platform Actions
mkdocs_resolve_absolute_urls_plugin-2.0.1-py3-none-any.whl Python 3 none any Details for mkdocs_resolve_absolute_urls_plugin-2.0.1-py3-none-any.whl

Total release size: 18.0 kB

Release files / mkdocs_resolve_absolute_urls_plugin-2.0.1.tar.gz

Download URL mkdocs_resolve_absolute_urls_plugin-2.0.1.tar.gz
Size 10.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ba1cbb09dcd43a7b6d7d4e2b77191217ef28a4d4062fbf90e1e6ef2c14c92ff3
BLAKE2b-256 checksum
How to use checksums
c415214c9280f363fea3cbbc372694f7dbe2aebce2a429630b21a90fce825b07
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / mkdocs_resolve_absolute_urls_plugin-2.0.1-py3-none-any.whl

Download URL mkdocs_resolve_absolute_urls_plugin-2.0.1-py3-none-any.whl
Size 7.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fef40d018a644c313e768caf4587141645c20d2325aed7aef74866a4f94b351e
BLAKE2b-256 checksum
How to use checksums
f318e223f98c17e5b59d65727cf6e959217461f8de71d5f47cd5d08b881a21d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for mkdocs-resolve-absolute-urls-plugin 2.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page