mkdocs-material/blog/2021/09/13/search-better-faster-smaller/

[giscus[bot]]

mkdocs-material/blog/2021/09/13/search-better-faster-smaller/

How we rebuilt client-side search, delivering a better user experience while making it faster and smaller at the same time

https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller/

[dobl1]

Hello, awesome job, on the user interface improvements.
What about adding the ability to filter the search using tags. To only target a subset of the pages (useful when the doc is covering different topics / products / techs, ...)

So in the search bar having a filter icon and filters from a pre-configured list.

[squidfunk]

Thanks! I'd add this to my list of ideas how to further improve the experience. A filtering or faceting option could be a good addition.

[TRaSH-]

would be nice to have option to ignore certain part of the docs to be shown in the search results
like ignore everything in /something/*

[squidfunk]

This can already be done with a combination of the built-in meta plugin and search exclusion 😊

[bs-jena]

Hello Martin,
I don't know where to raise my concern because it is certainly not a bug nor a feature request, just an "unlucky" combination of some issues. Sorry for that. Here's my question:
Now with the release 9, the new search is available for all users. I understand that this entails that third-party plugins that alter the search index no longer work. We used mkdocs-exclude-search to exclude entire directories from the search (like snippets/*). You suggest to solve this using your meta plugin and your search exclusion, but the meta plugin is for sponsors only. I don't think it's good practice to disable a feature (support for mkdocs-exclude-search), leaving no other option than paying. Or is there a way I'm not aware of for excluding entire directories from the search without adding a front matter to +100 files?
Best,
Bernd

[squidfunk]

I'm not sure why the mkdocs-exclude-search plugin shouldn't work anymore. If so, please create a bug report with a reproduction 😊 I've actually forgotten about the plugin, but using the meta plugin + the search exclusion pragma is one way of doing it. As I read the code, the mkdocs-exclude-search plugins reads the search index and filters it afterwards. This should still work. The format is still the same.

[bs-jena]

Thanks for looking into it and the quick reply. You say it should work -- so I will take a closer look to find out why it does not here. Maybe it's the new MkDocs version and the extension itself. We stick to the previous versions in production meanwhile. Thanks again, best

[MaximilianKohler]

I'm wondering if this fixes a few issues I've noticed:

1. If I search a string like Assessment of psychotropic-like properties of a probiotic formulation Read the Docs theme can find the string and return it as the first result, but Material theme can't.
2. Neither theme gives results for URLs; IE: https://www.ncbi.nlm.nih.gov/pubmed/
3. The search results don't seem to sort in "most matches first". IE: most of the first entries say Missing: Assessment psychotropic properties probiotic formulation
4. I wanted to find out all the options for !!!, but https://squidfunk.github.io/mkdocs-material/reference/admonitions/?q=!!! gives 0 results.

I've just set up Mkdocs for my site, but now I'm thinking of porting to something else because the search seems totally useless.

I've searched but there's 100+ issues: https://github.com/squidfunk/mkdocs-material/issues?q=is%3Aissue+search+results

[squidfunk]

Material for MkDocs has a fundamentally different search implementation than ReadTheDocs, the latter of which uses a server-based solution (likely ElasticSearch). Of course, such a solution offers much more sophisticated capabilities than what we get with Lunr.js, but you'll need to maintain a server or pay somebody to do it for you 😊 Also, our search is one of the very, very few in SSGs/themes that is offline-capable. Search is a moving target – it's very hard if not impossible to build a one-size-fits-all solution. We offer quite some flexibility by configuring and tinkering with the search.separator, which is now a lot more flexible with version 9. Search for URLs is certainly not something we're optimizing for, as our users very rarely do that.

Note that our search is more targeted towards users entering keywords, not entire sentences. The reason why this may lead to sub-par results is that Lunr.js doesn't properly take token positions into account when ranking documents according to a query. This is something I'll definitely be looking into in the future, i.e., if we can retrofit span support (token a is near token b), since we already successfully extended the capabilities, but it's nothing that is available right now.

I've just set up Mkdocs for my site, but now I'm thinking of porting to something else because the search seems totally useless.

As always, use the technology that best fits your needs! 😊 Note that some users have successfully integrated ReadTheDocs search or Algolia into Material for MkDocs, which completely replaces the built-in search. Furthermore, you might be interested to hear that ReadTheDocs is working on a native integration of their search into our search field, which would mean that you could deploy Material for MkDocs and ReadTheDocs and get the best of both worlds. It's been a few months since I've talked with @ericholscher of ReadTheDocs, so maybe they've made good progress on that front!

[MaximilianKohler]

Thoughts on this search? https://hugo-book-demo.netlify.app/docs/shortcodes/hints

Is it portable to Material theme and would you want to?

I couldn't get that theme to work on my PC, but when testing the search on their demo site it seems to work well. It can find sentences and URLs (see Buttons page).

I'm a novice trying to port a github wiki that has lots of study titles & links that I'd want to be searchable.

There's a lot to like about Material theme, and I don't know of anything better yet.

[squidfunk]

Is it portable to Material theme and would you want to?

I don't know, and no.

Note that search will get a major update later this year (given how many change requests there currently are). As always, we try to expand use cases on every iteration, but as I already mentioned in my previous comment, whole-sentence-search is not something we aim for. You might be better off with using a different theme or SSG if that is a mandatory requirement.

[StephenB87]

Would you ever consider an option to be able to give results for urls? This is a pretty common use case for us. Or do you know how I could modify the search separator to return those results?

[squidfunk]

I'm not entirely sure what you mean. Could I ask you to open a change request? With more information available, it would allow us to better understand the requirements and implications.