`archive_url_format: "{date}"` resulted in the exclusion of files from build

balansczerni commented 1 year ago

Context

I tried to set a short url for the build-in blog archive with archive_url_format: "{date}".

Bug description

Setting archive_url_format: "{date}" results in an error that excludes pages from the blog directory from being built by MkDocs.

mkdocs.yml:

plugins:
  - blog:
      archive_url_format: "{date}"

Files:

.
├─ docs/
│  └─ blog/
│     ├─ lorem/
│     │  └─ blog-page.md 👎
│     ├─ posts/
│     ├─ blog-page.md 👎
│     └─ index.md 👎
└─ mkdocs.yml

Error:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  A reference to 'blog/index.md' is included in the 'nav' configuration, but this file is excluded from the built site.
INFO    -  A reference to 'blog/blog-page.md' is included in the 'nav' configuration, but this file is excluded from the built site.
INFO    -  A reference to 'blog/lorem/blog-page.md' is included in the 'nav' configuration, but this file is excluded from the built site.
INFO    -  Documentation built in 0.16 seconds

Temp. fix:

Setting archive_url_format: "a/{date}" or leaving it default ("archive/{date}").

More tests:

I was curious if this bug would affect: custom category pages or hand made yyyy.md pages.

It turned out that these pages work properly...

.
├─ docs/
│  └─ blog/
│     ├─ category/
│     │  └─ custom-category-page.md 👍
│     ├─ lorem/
│     │  └─ blog-page.md 👎
│     ├─ posts/
│     │  └─ (some posts from 2020 and 2023 with "custom-category-page" category)
│     ├─ blog-page.md 👎
│     ├─ 2023.md  👍
│     ├─ 2020.md  👍
│     └─ index.md 👎
└─ mkdocs.yml

The bug is also present in the Insiders version.

EDIT: @squidfunk I got same issue with "categories_url_format: "{slug}" btw.

Reproduction

(Contrary to the name, these reproductions are not based on the Insiders version.)

Minimal reproduction:

9.2.5+insiders.4.40.1-archive-url-turn-md-excluded.zip

Reproduction from tests (yyyy.md + category/name.md):

9.2.5+insiders.4.40.1-same-bug-but-yyyy-cat-works.zip

mkdocs                     1.5.2
mkdocs-material            9.2.5
mkdocs-material-extensions 1.1.1

Steps to reproduce

Setup fresh venv.

python3 -m venv venv
. venv/bin/activate
pip install --upgrade --force-reinstall mkdocs-material
mkdocs new .

Setup mkdocs.yml with blog plugin archive_url_format: "{date}" option
Make some *.md's inside blog dir that do not cover dates (yyyy.md) or category names (category/name.md).
Run build.

Browser

No response

Before submitting

[X] I have read and followed the bug reporting guidelines.
[X] I have attached links to the documentation, and possibly related issues and discussions.
[X] I assure that I have removed all customizations before submitting this bug report.
[X] I have attached a .zip file with a minimal reproduction.

squidfunk commented 1 year ago

Thanks for reporting. Hmm, turns out it's harder than I though to support custom index pages while retaining complete freedom over how the navigation is defined (which the rewrite was all about). I'll look into it asap. In the meantime, you should use a discernable prefix for archive pages, i.e., archive. It's generally not advisable to drop the prefix archive and category, because the generated pages might clash with (or even overwrite) pages with the same filename.

squidfunk commented 1 year ago

The bug is also present in the Insiders version.

Custom index pages are currently only supported in the Insiders edition – it's a sponsorware feature which will be released to the community edition once the 'Chipotle' funding goal is hit. If you try to add custom index pages in the community edition, behavior will be undefined and the build will most likely not work, which is expected.

squidfunk commented 1 year ago

Fixed in a0280cb. I've taken the time and did a refactoring, unifying how views and pages are constructed. There might still be issues, as it's still a ground up rewrite of what we had before, but I feel that we made a big leap in the right direction!

squidfunk commented 1 year ago

Released as part of 9.2.6+insiders-4.40.2.

squidfunk / mkdocs-material