octoprint / mkdocs-site-urls

A MkDocs plugin that adds support for site-relative `site:` URLs.

MkDocs Site URLs Plugin

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

1. Install the plugin from PyPI

   pip install mkdocs-site-urls

2. Add the site-urls plugin to your mkdocs.yml plugins section:

   plugins:
     - site-urls

3. 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)
   
   ![Image](site:images/foo.png)

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.:

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.

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.

License

This project is licensed under the MIT license, see the LICENSE file for details.

mkdocs-site-urls's Issues

Allow for data

Hi!
I am trying to embed a pdf like this

<object data="site:arctifacts/my.pdf" style="width: 100%;height: 900px"></object>

Could you maybe try to modify theregex to add data to allow this?

Thank you!

Potential issues with internal links without proper mkdocs support

First off, thanks @foosel for this plugin!

A few concerns I have as I want to adopt this. I've seen some links breaking in this scenario where we do not use the supported MkDocs where you do relative linking to the markdown file.

For example:

[Not MkDocs supported](site:contribute/)
[MkDocs supported](site:contribute.md)

Assuming site_url: http://localhost:8000, this would render to:

<!-- this works as expected -->
<a href="http://localhost:8000/contribute/">Not MkDocs supported</a>

<!-- this breaks since the page is compiled to contribute/index.html -->
<a href="http://localhost:8000/contribute.md">MkDocs supported</a>

I'm fine technically going against the spec as this plugin basically addresses everything as an external link. I can't think of a case where this would be an issue as we're basically removing all internal linking, but I just wanted to raise this and get some discussion/feedback for anyone else who shares this concern.

Edit:

This plugin will also break offline mode for those currently using mkdocs-materials plugins.

I almost wonder if there would be a similar way you could detect configurable set of file endings (e.g. .md), that don't get processed. I'm happy to look into this, but would like to know if you know of a better approach.

Few links I don't want to lose:

• mkdocs/mkdocs#3276
• https://www.mkdocs.org/dev-guide/plugins/#events
• Plugin I'm using https://github.com/bitsondatadev/mkdocs-monorepo-plugin