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

[patrick-kidger]

I notice that Material overrides the default search plugin with its own. Whilst they have different entry points:

# site-packages/mkdocs-1.6.1.dist-info/entry_points.txt
[mkdocs.plugins]
search = mkdocs.contrib.search:SearchPlugin

# site-packages/mkdocs_material-9.6.7.dist-info/entry_points.txt
[mkdocs.plugins]
material/search = material.plugins.search.plugin:SearchPlugin

it seems that setting

# mkdocs.yml
plugins:
    - search

nonetheless grabs the material/search plugin rather than the built-in search plugin.

Is it possible to disable this behaviour, and use the Material theme with the default search plugin?

Context: we've found in patrick-kidger/equinox#984 that we get a degraded experience with material/search when searching for Python function/class documention provided mkdocstrings.

I'm aware that a new search experience is in the works (#6307), but until then I'm looking for an alternative solution.

[kamilkrzyskow]

Hi @patrick-kidger,

this should be possibile by adding a / to the plugin name to turn off the theme scope.

So /search.

Release notes, the best kind of docs 😂:

• https://www.mkdocs.org/about/release-notes/#version-141-2022-10-15

If that doesn't work in 1.6.1 I would have to look deeper.

[patrick-kidger]

Thanks for the response! I didn't appreciate that namespacing was being provided by mkdocs itself.

Unfortunately this actually just means that the search bar disappears entirely, presumably due to this statement:

mkdocs-material/material/templates/partials/header.html

Lines 48 to 54 in e66107e

	{% if "material/search" in config.plugins %}
	<label class="md-header__button md-icon" for="__search">
	{% set icon = config.theme.icon.search or "material/magnify" %}
	{% include ".icons/" ~ icon ~ ".svg" %}
	</label>
	{% include "partials/search.html" %}
	{% endif %}

[squidfunk]

I don't think MkDocs' search implementation will save you (if you're interested, here's a blog post on this topic). Have you tried tweaking the separator of the search plugin that is used for tokenization? It makes a big difference. For instance, the default is:

plugins:
  - search:
      separator: '[\s\-]+'

Interestingly, it doesn't even support multi-character separators (see blog post), so the + is actually a no-op. This is because of how lunr.js' tokenizer works, and why we completely replaced it. Now, here's the one we use for our docs:

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

I think with some experimentation you'll be able to improve results significantly. Also note that, yes, the new search will have much better defaults, but there will always be cases where some tweaking is necessary. However, the new search allows this basically everywhere.

[patrick-kidger]

Aha, this is awesome. Setting an alternate separator -- I used the one you use -- solves the problem. I think the essential change is allowing . to be a separator token, so that we can search for mylib.SomeClass by typing just SomeClass.

(For completeness, the default MkDocs search avoided this problem in a different way, by storing the equivalent search_index.json entry under just SomeClass.)

Thank you for your help!

[kamilkrzyskow]

Yeah, I forgot about this:

• mkdocs-material/material/templates/partials/header.html

  Lines 48 to 54 in e66107e

  	{% if "material/search" in config.plugins %}
  	<label class="md-header__button md-icon" for="__search">
  	{% set icon = config.theme.icon.search or "material/magnify" %}
  	{% include ".icons/" ~ icon ~ ".svg" %}
  	</label>
  	{% include "partials/search.html" %}
  	{% endif %}

Also now that I think about it, In general the search_index in the theme here is a bit different, and doesn't have "API" parity to the one generated in mkdocs. So the material frontend would not read it properly.

I answered too quickly without considering the XY problem carefully 😞
Good that squidfunk stepped in, because otherwise I would go on a trip down the hacky solution highway 👀 💦

[squidfunk]

No worries! Search is a topic we invested hundreds, probably thousands, of hours over the years. That's also why we decided to finally do a rewrite from scratch, as the situation has been pretty meh. It's important to know that the Material theme expects the Material search plugin, or at least a compatible index. MkDocs search plugin will not work with it, but its results are much worse than results with our current search implementation (which also has its problems that we fixed in the new search).