Regression with nav item direct linking to blog post in 4.40.3

[perpil]

Context

In a recent change, directly linking to a blog post from the nav exhibits strange behavior. The nav link works, but that specific blog post is missing the metadata sidebar and it is excluded from the blog index.

Bug description

On my site, I link to a specific blog entry under a nav entry called Mission. This normally works fine, but in insiders 9.2.7+4.40.3 I get an error: A reference to 'blog/posts/mission.md' is included in the 'nav' configuration, but this file is excluded from the built site. The nav link works, and it shows the blog entry, but it is missing the blog metadata like date and author. Other posts that aren't linked in the nav show up in the blog index, but the mission.md one is missing.

Related links

• Reporting a bug
• archive_url_format: "{date}" resulted in the exclusion of files from build #5904

Reproduction

9.2.7+insiders.4.40.3-blog-entry-in-nav-not-working.zip

Steps to reproduce

1. mkdocs serve
2. See the error A reference to 'blog/posts/mission.md' is included in the 'nav' configuration, but this file is excluded from the built site.
3. Click the Mission nav item, note it does not have metadata
4. Click the Blog nav item, note there is no entry for the mission blog post.
5. Click continue reading and note the post called Entry has metadata.

Browser

No response

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.

[squidfunk]

Thanks for reporting. What was the last version working? I suspect the warning is caused by the latest refactoring of the plugin, which was necessary to make it work with other third-party plugins like awesome-pages or static-i18n. The blog posts must be temporarily excluded, because, otherwise, MkDocs will add all of them to the navigation. This is unusual for blogs, because blog posts are usually linked from paginated indexes.

We already filed an upstream issue 3 weeks ago, so we could mark posts as "not in nav", but not "excluded":

• Setting InclusionLevel.NOT_IN_NAV still adds pages to nav mkdocs/mkdocs#3336

Until the upstream issue is resolved, fixing the problem reported is blocked, because we currently have to hack around it.

[squidfunk]

Okay, I have an even better idea now. Fixing the issue mentioned in my last comment will fix the warning that is printed. However, the problem that the page is overwritten stems from the fact that MkDocs will ignore that pages are excluded from the navigation when they are linked in the navigation, and always create (= overwrite in case of blog posts) them. In fact, if the following PR that I proposed several days ago gets merged and released, the problem is gone:

• Allow plugins to provide their own Page mkdocs/mkdocs#3367
• Allow plugins to override Page when populating navigation mkdocs/mkdocs#3366

[squidfunk]

Fixed in 3f87fe0. I've extended the temporary hack that works around the limitations mentioned in mkdocs/mkdocs#3366 and fixed by mkdocs/mkdocs#3367 which we already use for the blog entrypoint. Applying them to posts and views fixes the problem for them as well. Once the mentioned PR is merged, the entire part of the code can be removed.

Note that the problem was not exclusive to Insiders, but applies to the community edition blog as well.

[perpil]

Thanks for the quick fix! I verified it works, but the nav uses the title of the blog post instead of the nav key. I've attached a repro demonstrating this. Is this change in behavior intentional?

In this repro, the nav previously would be set to Mission, now it is set to The Mission Statement

9.2.7+insiders.4.40.3-nav-using-title.zip

Also per your question above about the last known version this was working. According to the metadata in my published site it was working with: mkdocs-1.5.2, mkdocs-material-9.2.3+insiders-4.39.3

[squidfunk]

Thanks again for the feedback and reproduction.

Also per your question above about the last known version this was working. According to the metadata in my published site it was working with: mkdocs-1.5.2, mkdocs-material-9.2.3+insiders-4.39.3

If you're referring to the post title being set to the nav key – that is weird, because posts never had explicit titles set as they are not meant to be linked in the navigation, so the fact that this worked before was definitely accidental and not intended. The problem is: we can't allow to link posts in the navigation, because we must process posts before the navigation is constructed because several parts of the blog plugin rely on this information.

This is orthogonal to what you're trying to achieve and the reason why the behavior is not in line with what you'd expect from MkDocs. Once mkdocs/mkdocs#3367 is merged, post titles can't be set in the nav at all, and IMHO that is correct. Thus, we're not considering this a bug but undefined behavior as you're outside of what is supported by the blog plugin.

You can work around this restriction by using a relative link:

nav:
  - Blog:
    - blog/index.md 
  - Mission: blog/2023/09/01/the-mission-statement/
validation:
  nav:
    not_found: ignore

[perpil]

I thought the key in the nav would set the nav text, so I was a bit surprised that it was resolving to the destination title, but the workaround works for me. Thanks!

[squidfunk]

Yes, it sets the nav text, for normal pages. Blog posts are not normal pages, they are excluded from the navigation, because that's usually not how blogs work ☺️ We'll clarify this better in our docs. Glad the workaround works for you!

[squidfunk]

Released as part of 9.2.8.