When using the "--dirty", the search plugin fails

[Xiaokang2022]

Context

• Python: 3.13.0
• OS: Windows11 23H2
• mkdocs: 1.6.1

Bug description

In exceptional cases, the search plugin will fail. See the reproduced instructions below.

Related links

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

Reproduction

9.5.42-search-fail-with-dirty.zip

Steps to reproduce

1. Build once, with or without "--dirty"
2. Build again, this time with "--dirty"
3. At this point, the content of the site/search/search_index.json is incorrect

Browser

Edge

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! Unfortunately, the whole handling of incremental builds is a problem of MkDocs which I already reported. Some work has been started to improve the situation, but I'm not sure what the status is.

The problem is that the search plugin needs MkDocs to read all pages, but the --dirty flag instructs it to only read the pages that changed. Thus, the search plugin does not see the pages to extract the information from, and writes an empty index. The general advise is to never use --dirty with mkdocs build, as it leads to incorrect navigation.

In fact, it it not dependent on Material for MkDocs – the situation is the same for the mkdocs and readthedocs themes. We can't fix it here, as we do not control how MkDocs builds. For this reason, it's an upstream issue.