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_URLenvironment variable when noroot_urlis 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 withurl_versioning_schemeset tomultiple_versions_with_translations@<version>: Optional version override to switch to a specific version. Must be used withurl_versioning_schemeset to eithermultiple_versions_with_translationsormultiple_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.