MkDocs 1.5 and the !relative YAML tag

[pawamoy]

What's the problem this feature will solve?

MkDocs 1.5 introduced the !relative YAML custom tag: https://www.mkdocs.org/user-guide/configuration/#paths-relative-to-the-current-file-or-site. It is used to declare paths in the config as relative to the config file directory, the docs directory, or the current Markdown page directory. This was needed for Markdown extensions which know nothing about MkDocs, whereas plugins receive the config file path and therefore are able to compute relative paths themselves.

Paths need to be relative for the -f option of mkdocs serve/build to work propertly. Relying on the current working directory is not compatible with this option.

Describe the solution you'd like

I searched the issues and PRs but couldn't find anything related, so I assume support for this custom tag was not implemented, and your safe YAML loader would probably fail to load/restore it?

[stsewd]

Ad mentioned in readthedocs/addons#72, we will remove our overrides from the mkdocs.yml file. You can also make use of the build.command feature to run mkdocs with any options you want https://docs.readthedocs.io/en/stable/build-customization.html#override-the-build-process, RTD won't override the config file when using that option.

[humitos]

In case you want to try out this new Read the Docs addons approach, you can opt-in by enabling beta addons in your project from the project's admin page using the new beta dashboard at https://beta.readthedocs.org. I'd appreciate any feedback you may have regarding this approach.

Eventually, this new "addons approach" will be the default for all the projects and Read the Docs will not manipulate the build process anymore, allowing custom tags like !relative, and any other changes, to work in the same way as building locally.

[humitos]

we will remove our overrides from the mkdocs.yml file

We already removed this override in #11206, so users can use !relative in their mkdocs.yml without problems.

We wrote a blog post about this at https://about.readthedocs.com/blog/2024/03/mkdocs-yaml-manipulation/