# MkDocs Site URLs Plugin
[](https://octoprint.org/conduct/)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
[](https://github.com/pre-commit/pre-commit)
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/path/` | `/path/images/foo.png` |
| `site:images/foo.png` | unset/empty | `/images/foo.png` |
**Please note**: This plugin requires MkDocs 1.5 or higher.
## Getting Started
1. Install the plugin from PyPI
```bash
pip install mkdocs-site-urls
```
2. Add the `site-urls` plugin to your `mkdocs.yml` plugins section:
```yaml
plugins:
- site-urls
```
3. Start using site-relative URLs in your Markdown files by prefixing them with `site:`:
```markdown
[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.:
```yaml
plugins:
- site-urls:
attributes:
- href
- src
- data
- data-url
```
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.
```yaml
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 `/`.
The plugin will extract the path prefix to use from the [`site_url`](https://www.mkdocs.org/user-guide/configuration/#site_url).
configured in your `mkdocs.yaml`. If no `site_url` is configured, it will default to using the root path `/`.
## How it works
The plugin hooks into the [`on_page_content` event](https://www.mkdocs.org/dev-guide/plugins/#on_page_content)
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
1. Create a venv & activate it, e.g. `python -m venv venv && source venv/bin/activate`
2. Install the dev requirements: `pip install -r requirements-dev.txt`
3. 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](https://github.com/OctoPrint/mkdocs-site-urls/blob/main/LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/OctoPrint/mkdocs-site-urls",
"name": "mkdocs-site-urls",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mkdocs, plugin",
"author": "Gina H\u00e4u\u00dfge",
"author_email": "gina@octoprint.org",
"download_url": "https://files.pythonhosted.org/packages/3f/9c/d02d2e089b128e9d84c46fb757738ae56bffce33b5ad90dec4f280d03436/mkdocs_site_urls-0.3.1.tar.gz",
"platform": null,
"description": "# MkDocs Site URLs Plugin\n\n\n\n\n[](https://octoprint.org/conduct/)\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n[](https://github.com/pre-commit/pre-commit)\n\nA MkDocs plugin that adds support for site-relative `site:` URLs.\n\nExample:\n\n| URL | site_url | resulting URL |\n| --------------------- | --------------------------- | ---------------------- |\n| `site:images/foo.png` | `https://example.com/` | `/images/foo.png` |\n| `site:images/foo.png` | `https://example.com/path/` | `/path/images/foo.png` |\n| `site:images/foo.png` | unset/empty | `/images/foo.png` |\n\n**Please note**: This plugin requires MkDocs 1.5 or higher.\n\n## Getting Started\n\n1. Install the plugin from PyPI\n ```bash\n pip install mkdocs-site-urls\n ```\n2. Add the `site-urls` plugin to your `mkdocs.yml` plugins section:\n ```yaml\n plugins:\n - site-urls\n ```\n3. Start using site-relative URLs in your Markdown files by prefixing them with `site:`:\n ```markdown\n [Link to another page](site:another-page/relative/to/the/site/root)\n\n \n ```\n\n## Configuration\n\nBy default the plugin will replace URLs in `href`, `src` and `data` attributes. You can configure the attributes to replace\nby setting the `attributes` option in your `mkdocs.yml`, e.g.:\n\n```yaml\nplugins:\n - site-urls:\n attributes:\n - href\n - src\n - data\n - data-url\n```\n\nBe advised that in case of any customization on your part you need to include the default attributes as well if you want\nto keep them, as the default list will not be included automatically anymore.\n\nIf `site:` as the prefix does not work for you for any reason, you can also configure that,\ne.g.\n\n```yaml\nplugins:\n - site-urls:\n prefix: \"relative:\"\n```\n\nThis can also be used to interpret absolute URLs like `/example/file.png` as relative,\nby setting the `prefix` to `/`.\n\nThe plugin will extract the path prefix to use from the [`site_url`](https://www.mkdocs.org/user-guide/configuration/#site_url).\nconfigured in your `mkdocs.yaml`. If no `site_url` is configured, it will default to using the root path `/`.\n\n## How it works\n\nThe plugin hooks into the [`on_page_content` event](https://www.mkdocs.org/dev-guide/plugins/#on_page_content)\nand replaces all URLs in the configured attributes (by default `href`, `src` or `data`) in the rendered HTML with the corresponding site-relative URLs.\n\n## Development\n\n1. Create a venv & activate it, e.g. `python -m venv venv && source venv/bin/activate`\n2. Install the dev requirements: `pip install -r requirements-dev.txt`\n3. Install the `pre-commit` hooks: `pre-commit install`\n\nYou can run the tests with `pytest`.\n\nTo build the docs, install their dependencies as well (`pip install -r requirements-docs.txt`),\nthen run `mkdocs build`.\n\n## License\n\nThis project is licensed under the MIT license, see the [LICENSE](https://github.com/OctoPrint/mkdocs-site-urls/blob/main/LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin that adds support for site-relative URLs",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/OctoPrint/mkdocs-site-urls",
"Source": "https://github.com/OctoPrint/mkdocs-site-urls"
},
"split_keywords": [
"mkdocs",
" plugin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c3d34e93e993e3558fe70dc6ecda0e65694389b523dcebfa267515958cf99984",
"md5": "35fd1bd0c710a35653637523ba31d9a8",
"sha256": "e13f606e3de0fe52bfa7c152940a32fb0445a4a0e452b0387062a2ffe70e1662"
},
"downloads": -1,
"filename": "mkdocs_site_urls-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35fd1bd0c710a35653637523ba31d9a8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6365,
"upload_time": "2025-09-04T08:40:23",
"upload_time_iso_8601": "2025-09-04T08:40:23.211488Z",
"url": "https://files.pythonhosted.org/packages/c3/d3/4e93e993e3558fe70dc6ecda0e65694389b523dcebfa267515958cf99984/mkdocs_site_urls-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3f9cd02d2e089b128e9d84c46fb757738ae56bffce33b5ad90dec4f280d03436",
"md5": "7a3fdccba4ea6d0e9572db94753da3d9",
"sha256": "6c39b4aca9d0d29d747513bb679f5cc4e5957e37895ea5a12589e139ed1af3a9"
},
"downloads": -1,
"filename": "mkdocs_site_urls-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "7a3fdccba4ea6d0e9572db94753da3d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5887,
"upload_time": "2025-09-04T08:40:24",
"upload_time_iso_8601": "2025-09-04T08:40:24.222458Z",
"url": "https://files.pythonhosted.org/packages/3f/9c/d02d2e089b128e9d84c46fb757738ae56bffce33b5ad90dec4f280d03436/mkdocs_site_urls-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 08:40:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OctoPrint",
"github_project": "mkdocs-site-urls",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-site-urls"
}
JSON
