MkDocs assumes absolute paths start from the root of the hosted website, like https://localhost/. For example, an absolute path like /assets/image1.jpg becomes https://localhost/assets/image1.jpg, which is correct if MkDocs is hosted at the root.

When the server root is not the same as the MkDocs root, this plugin lets you define a webcontext to prepend to these absolute paths. The webcontext path (e.g., /projectname/documents) replaces the default root (/).

• Converts absolute image paths in Markdown to be relative to a specified web context.
• Converts image src attributes in HTML embedded in Markdown.
• Converts url("/path") references inside CSS files.
• Supports Markdown reference-style image and link syntax.
• Debug and info logging of replacements.

1. Install the plugin:

   pip install mkdocs-webcontext-plugin

   Or using Poetry:

   poetry add mkdocs-webcontext-plugin

2. Enable the plugin in your mkdocs.yml:

   plugins:
     - webcontext:
         context: foo/bar

The plugin modifies the following path formats:

• Markdown links: [title](/path/image.png)

• Markdown reference links:

  [logo]: /assets/logo.png

• HTML image tags: <img src="/assets/img.png">

• CSS url() paths: url("/assets/bg.jpg")

These paths will be rewritten to start with your defined context.

After your site is built, the plugin will scan all .css files in the output directory and rewrite any url("/...") references to use the defined context.

Rewrites are logged at the DEBUG level. Updated CSS files are logged at the INFO level.

This plugin was inspired by and built with guidance from:

• byrnereese/mkdocs-plugin-template
• sander76/mkdocs-abs-rel-plugin