Deprecation blocks strict build when migrating to newer version

[threadedstream]

Hi! Recently, I've upgraded mkdocs-material to version 9.5.5 from 8.5.11 and happened to notice that min_search_length option is deprecated now. I also decided to look into mkdocs repo, but didn't find support for it there. We use it extensively in our projects, so I need to know if there's an alternative. Thank you

[threadedstream]

We build our docs with strict mode enabled, so we really need to find solution here :)

[kamilkrzyskow]

If you're willing to use the old search you can set /search in the plugins:

plugins:
  - /search

this will load the default variant from MkDocs, instead of the newer search introduced in v9 of the theme

EDIT:

Ah that's not entirely correct, I stumbled again on the same issue. 😞
The frontend also expects the new search_index from the new search plugin.
So you'd also have to reimplement the search box, as in modify the search.html template and JavaScript

[threadedstream]

@kamilkrzyskow thank you! I compiled it now with prefixed with slash "search" and it worked. Now I see that it also affects js/html part, which is sad. Do I need to modify search.html template and JavaScript in every generated doc?

[kamilkrzyskow]

I'm not sure how you generate the docs, but as mkdocs is at the core, then each of the pages uses relative URLs, so yes, each of the docs would have to contain a "module" that would handle the search as it was before.

You'd use the customization approach which would take your files at build time:
https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme

As far as I know mkdocs-material has a separate search.js worker now, so it should be possible to extract the logic from version 8.5 to keep it in the new version. However, I don't know of anyone doing it, so you'd have to take the initial cost of researching the solution.

Maybe it's a case of XY problem, and maybe you don't really have to fight for the older implementation, and instead try to build your own min_search_length solution to work with the new version. Basically assess the cost and benefits, how does the min_search_length help you?

[threadedstream]

Would it affect the search much if we remove this option from config? In majority of configs the min_search_length equals to 3, which is a default value if I'm not mistaken

[kamilkrzyskow]

Would it affect the search much if we remove this option from config? In majority of configs the min_search_length equals to 3, which is a default value if I'm not mistaken

I never used this option myself, so you'd have to provide an example where it's really useful.
The newer search implementation introduced in 9.0 works better in most cases, but people had issues in the past, which can also be resolved using another config option. You can read up on it in the sibling discussion:

• Is it possible to disable Material's search plugin in favour of the one built-in to MkDocs? #8116

[threadedstream]

@kamilkrzyskow do you have any ideas regarding safe upgrade? We got 900 docs with failing builds out of 1045 and lion's share of errors related to unsupported options specified in config for the search plugin (with min_search_length being the leader).

UPD. We changed version to 9.5.33 which also triggered bumping mkdocs to version 1.6.1

[kamilkrzyskow]

So how did it pass the local tests and created the issue with 900 failing builds? Seems like the local test data doesn't represent the full extent of used configurations, and matches the ones that did not fail out of the 1045

[threadedstream]

No, it's not the test running in CI. I just wrote the script that did the job.

[threadedstream]

The docs being tested are the same ones hosted in production

[kamilkrzyskow]

@threadedstream

Following the example I prepared before in:

• Group plugin breaks if environmen value is "1", must be "true" to work #7976 (comment)

I made a quick script to suppress the warning and ignore the value:

[EDIT: The script below was simplified to directly target the suppression, but the example in the link above could be used to filter all sorts of values similar to the mkdocs-nype __init__.py]

# https://github.com/squidfunk/mkdocs-material/issues/7976#issuecomment-2649651039

from material.plugins.search import config as config_module
from mkdocs import __main__ as mkdocs_main
from mkdocs.config.config_options import Optional, Type


class MySearchConfig(config_module.SearchConfig):
    min_search_length = Optional(Type(int))

def main():
    config_module.SearchConfig = MySearchConfig
    mkdocs_main.cli()


if __name__ == "__main__":
    main()

Save it as myrunner.py and then in CI use python myrunner.py --strict --some-other-mkdocs-flags

[threadedstream]

Can I turn this script into a plugin so I don't need to delete these unsupported options in configs of 900 projects? So that mkdocs automatically uses my plugin when it sees plugins: search in the config.

[kamilkrzyskow]

What do you mean by that? Adding plugins or hooks does require changing the mkdocs.yml file, so if you're going to change the config files, then why not delete the value?

I would assume you have some global CI pipeline that manages the deployment for all docs projects, so you can just apply the script with the change at the CI level.

[threadedstream]

Actually, it's not a global CI pipeline, we have a dedicated service that compiles and publishes docs of a project right after merging code to master. By compilation I mean running mkdocs with some flags

[kamilkrzyskow]

That's what I meant, you "have a dedicated service that compiles and publishes docs of a project right after merging code to master"
so you have a global service that is in a relation 1:M, one service logic compiles any of these projects if any of them gets updated.

In that service location, if you can modify the filesystem to implement the runner.py script above or modify the Python packages directly to change the logic of the search plugin, then that's the place where changing it would be the easiest.

Elaborate on this service, what is it? It has to run mkdocs build at some point to compile the docs, right?
Instead of the mkdocs build you'd run the python myrunner.py

Either that or I'm missing something about your setup 🤔

[threadedstream]

@kamilkrzyskow Closing the discussion for now. Thank you very much for help!