Use a placeholder to simplify relative asset links.

[yves-chevallier]

Introduction:

Mkdocs encounters difficulties when handling absolute links, especially in conjunction with certain plugins. By default, Mkdocs validates links using the following configuration:

validation:
  links:
    absolute_links: info

This setup generates a warning for every absolute link present in the documentation. Changing the validation configuration is not a viable option as it may lead to compatibility issues with some plugins. Moreover, using only relative links can be cumbersome and error-prone, particularly when the location of a page changes, necessitating updates to all relative links.

For example:

![Image]('../../../../assets/image.png')

Solution:

To simplify the process, I wrote a hook that converts links with a placeholder {assets} to relative links. This hook assumes that the assets folder is located in the docs/assets directory. It allows you to write links in a simplified manner, as shown below:

![Image]({assets}/image.png)

Implementation:

Here is the hook currently used in my documentation:

import re
import mkdocs
import os
from pathlib import Path

RE = re.compile(r"(\[[^\]]+\]\(){assets}([^\)]+)\)")

@mkdocs.plugins.event_priority(100)
def on_page_markdown(markdown, page, config, files):
    page_url = Path(page.file.url).resolve()
    assets_dir = Path('./docs/assets').resolve()
    relpath = os.path.relpath(assets_dir, page_url.parent)
    return RE.sub(r"\1" + relpath + r"\2", markdown)

Discussion:

Is this a case of an XY-Problem? Despite exploring various alternatives, this solution currently seems to be the most effective. However, I'm open to suggestions for better approaches that might resolve the issue more efficiently.

[kamilkrzyskow]

Nice hook, the usage of relative links is mandated by the "keep things compatible with other Markdown processors like GitHub or VS Code or keep things standardized to be able to switch to other static site generators more easily" idea. Some users don't need this kind of approach and prefer the ability to write paths more easily.

There was a plugin for this:

• https://github.com/zachhannum/mkdocs-autolinks-plugin
  but I'm not sure if it is still working as expected.

The validation: absolute_links approach is rather new, came with 1.6.0 and it was introduced in a non-breaking way, so plugin developers need to opt-in to make use of it.

As for a quick code review:

• You can use config.docs_dir to access the absolute str path to the docs dir, it gets resolved during the validation procedure,
• You can use page.file.abs_src_path to access the absolute str path to the file,
• You can use Path().as_posix() to get paths with / on Windows.

As for the meta analysis, assuming large amount of files 1000+ with many links per page, using regex to find links and replacing them will decrease performance, so then it would be better to either hack into the MkDocs internals (there is a list of relative docs paths to File objects) or maybe use a markdown extension and modify links as they come for better performance.🤔

[FredZinelli]

Shameless plug... 'x)

I wrote a plugin for such a kind of things (internal references only) where the main idea is to avoid writting any kind of address manually and work instead with various identifiers. It provides autocompletion (that is... when using a VSC-like editor), validation of all the references, warns the user when something wrong is found (unknown identifiers ; it also validates relative paths written "the normal way").

Here it is: mkdocs-addresses (docs)

• Works with files
• Works with anchors/ids whitin md pages
• Works with external references ([material][material-ref])
• Links/addresses aren't written anymore, only the corresponding references. Example:

  # title { #specific-id }
  
  links are now written [like this](--specific-id)
  Also works for images: ![](!!img_png) for a file `assets/img.png` 
  ...and much more.

• Provide references + markdown snippets through autocompletion
• Validate all the references and links found in the documentation (internal links or files)
• Warn if something outdated is found anywhere
• White lists / black lists of things to check or not check, in case troubles are encountered in some situations

Note that:

• it's rather slow on huge documentations, though (there are ways to speed up the things a bit).
• It's kinda hard to take in hand (because there are a lot of tools/options involved)

If ever that may help...

[yves-chevallier]

I like your short !! syntax. But I will then reduce the only one short notation. For internal references I like the mkdocs-autorefs syntax: [caption][link].

[FredZinelli]

Again, only the id is used, and this is applying across multiple files. This means that if { #scpecific-id } is defined in, let's say docs/blabla/blibli/index.md, one can use ... [see specifics](--specific-id) from any other file of the documentation, whatever its location.

Moreover, the plugin isn't only about references, but all the additional features that come with it (auto-completion snippets in VSC-like, validations, ...).