You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A MkDocs plugin that adds support for site-relative site: URLs.
Example:
URL
site_url
resulting URL
site:images/foo.png
https://example.com/
/images/foo.png
site:images/foo.png
https://example.com/bar/
/bar/images/foo.png
Please note: This plugin requires MkDocs 1.5 or higher.
Getting Started
Install the plugin from PyPI
pip install mkdocs-site-urls
Add the site-urls plugin to your mkdocs.yml plugins section:
plugins:
- site-urls
Start using site-relative URLs in your Markdown files by prefixing them with site::
[Link to another page](site:another-page/relative/to/the/site/root)
Configuration
By default the plugin will replace URLs in href, src and data attributes. You can configure the attributes to replace
by setting the attributes option in your mkdocs.yml, e.g.:
Be advised that in case of any customization on your part you need to include the default attributes as well if you want
to keep them, as the default list will not be included automatically anymore.
If site: as the prefix does not work for you for any reason, you can also configure that,
e.g.
plugins:
- site-urls:
prefix: "relative:"
This can also be used to interpret absolute URLs like /example/file.png as relative,
by setting the prefix to /.
How it works
The plugin hooks into the on_page_content event
and replaces all URLs in the configured attributes (by default href, src or data) in the rendered HTML with the corresponding site-relative URLs.
Development
Create a venv & activate it, e.g. python -m venv venv && source venv/bin/activate
Install the dev requirements: pip install -r requirements-dev.txt
Install the pre-commit hooks: pre-commit install
You can run the tests with pytest.
To build the docs, install their dependencies as well (pip install -r requirements-docs.txt),
then run mkdocs build.
License
This project is licensed under the MIT license, see the LICENSE file for details.
About
A MkDocs plugin that adds support for site-relative `site:` URLs.