MkDocs-Material Blog plugin messing up links?

[Andre601]

Currently encounter some odd behaviour while using the Material for MkDocs theme...

I cannot really tell if it is caused by the blog plugin, or if there are other causes that make issues...

Either way, the issue is as follows:
I have a folder structure docs/posts/<year>/ for my blog posts. Now MkDocs 1.5.0 reports the following thing to me on serve:

INFO    -  Doc file 'posts/2020/12-24-truth-and-lies.md' contains an unrecognized relative link '../12-20-in-defense-of-spigotmc', it was left as is.

The problem is, that adding a .md extension breaks stuff in multiple ways. It first of all reports the following warning now:

WARNING -  Doc file 'posts/2020/12-24-truth-and-lies.md' contains a relative link '../12-20-in-defense-of-spigotmc.md', but the target 'posts/12-20-in-defense-of-spigotmc.md' is not found among documentation files.

This for once seems to indicate a faulty path resolving? Because the reported path is /posts/12-20-in-defense-of-spigotmc.md while the actual path (which the link itself also resolves to) is /posts/2020/12-20-in-defense-of-spigotmc.md

In addition is the effective link on the rendered site not properly resolved, still pointing to the md file rather than the actual site, meaning the link is ../12-20-in-defense-of-spigotmc.md which results in a 404.

This is not that big of a deal for me. I can just use the relative URLs as I did in the past and ignore the info lines, but I preferrably would like to have those gone alltogether if possible...

Also, not sure if I should report that wrong file-path resolving to MkDocs or not... I'm generally confused and don't know if any of this is a bug and from who it is caused...

[squidfunk]

The blog plugin allows to link to other blog articles or other pages by just using the source path (not the computed path/slug). The new warnings are likely related to the new MkDocs version. Please create a new issue with a minimal reproduction, so we can adjust for the new MkDocs behavior.

It's worth noting that the blog plugin jumps through some hoops to supress the "files not in nav" warning that MkDocs prints, because the posts should not be linked in the nav entry. This seems to have become simpler with MkDocs 1.5.0, as we can now mark certain files as "deliberately not linked in nav". We should migrate to the new MkDocs API for marking all blog posts as generated files.

In any way, an issue to track progress with a minimal reproduction is what we need here. Thanks! 😊

[Andre601]

I addressed this in the MkDocs repository and fixed it.

Here's the comment explaining most of it as I can't explain it myself:
mkdocs/mkdocs#3312 (comment)

[squidfunk]

That's great to hear! Could you please provide a little more context, so other users can benefit from your work?

[Andre601]

Added a comment link. Can't really explain the solution simply because I don't get it...

[squidfunk]

Ah thanks. The comment says exactly what's in our documentation: Link to and from blog posts exactly like you do for pages

While post URLs are dynamically computed, the built-in blog plugin ensures that all links from and to posts and a post's assets are correct. If you want to link to a post, just use the path to the Markdown file as a link reference (links must be relative).

We'll improve the documentation so that it's more apparent that we're talking about file system paths.