mkdocs validation warnings when referencing sub-project file via absolute link

[Blacksmoke16]

Context

Related third-party discussion/info, relating to an upcoming mkdocs 1.6 feature. Initially created an issue upstream in mkdocs repo, but narrowed down the issue to be specific to the projects plugin.

• https://www.mkdocs.org/user-guide/configuration/#validation
• False positive relative_to_docs absolute path validation warning mkdocs/mkdocs#3589
• Validation of absolute links relative to docs root mkdocs/mkdocs#3485

Bug description

mkdocs 1.6 (yet to be released), added a new validation mode for absolute_links called relative_to_docs that allows using/validating absolute links and replacing them with relative ones. At first glance this seemed to be a good way to link to sub-projects via the projects plugin.

However it seems to not work so nicely when you get into it. When linking to a sub-project from a root project, a validation warning is emitted that the target is not found. E.g. /my_app/thing linking to projects/my_app/docs/thing.md.

Based on some of the discussion linked earlier:

Links need to be always to .md files that exist in docs dir.

Notice the link works, but in order for the warning to not be emitted needs to point at a valid file, of which /my_app/thing.md (404), /my_app/thing/thing.md (404), /my_app/thing/thing.html (works), all still emit the warning even if the link is valid and works.

Related to #5800 (reply in thread), is possible I may just have to wait for this functionality vs using the normal mkdocs absolute links. But in either case it would be a nice benefit if this option could make use of the mkdocs validation.

Related links

• Reporting a bug
• https://squidfunk.github.io/mkdocs-material/plugins/projects/

Reproduction

mkdocs-testing.zip

Steps to reproduce

1. python3 -m venv venv
2. . venv/bin/activate
3. pip install -r requirements.txt
4. mkdocs serve

Notice in the build logs:

WARNING - Doc file 'index.md' contains a link '/my_app/thing', but the target is not found among documentation files.

Browser

Chrome

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction using the built-in info plugin.

[squidfunk]

Thanks for reporting. MkDocs 1.6 is not out yet, and I'm not sure when the maintainers of MkDocs will consider it ready for being released. I'm also desperately awaiting the next release and am closely following what's happening, but unfortunately, not much lately.

Once it is out, we can evaluate and consider how we can improve support of the projects plugin for this feature, but please understand that we just cannot support unreleased features which might still be subject to change. Additionally, the canonical way to support interlinking between projects is the project:// URL. Absolute links that point outside of projects will likely not be supported, because there's no way we can know that this points to a project.

Closing, but we may reconsider once MkDocs 1.6 is out actually shipping this feature.

[Blacksmoke16]

Looks like https://github.com/mkdocs/mkdocs/releases/tag/1.6.0 was released today if this is something to re-consider. Otherwise I'll just wait until project:// is available as that would most likely support similar validation? Assuming you can link from one project to another.

[squidfunk]

Yup, I've seen it as well. I don't think this helps, because I believe that MkDocs should and will only validate files inside docs_dir, and not outside of that, because everything outside of docs_dir is not part of your project. Projects are and must be located outside of docs_dir or, so this it not of much help. Happy to be proven wrong, if you can spare some time.

We still need to find out the specifics of linking between projects. For instance, what happens if you tie together some projects that you also build separately? What happens if you then build a subproject separately that contains a link to another project? I still haven't found the perfect solution for it, but we'd most likely need some kind of fallback that defines what happens when you build them alone. Links could also possibly be just removed, but that doesn't make sense for links in the navigation. There are many case to consider.

I also must excuse myself, as I'm currently heavily working on #6307, but we'll see how we can improve the projects plugin with a little more feedback in the near future ☺️ Until then, please be invited to share more feedback here and on our discussion board!