Custom search clarification

[bradumbaugh]

I'm going to start experimenting with custom search a bit, but I'd like to be certain that my understanding of this feature is correct before I get too far into it...

Am I correct that a custom web worker could pass a search query (entered in the default search UI) to an external service to fetch search results—and then I could massage those results and pass them back to Material for MkDocs to render in its default search/results UI (as opposed to a UI provided by the third party)?

As one follow-on question: I'm not clear how this approach would play with other search-related features (tags, boosts, suggestions, highlighting, etc.)—but I assume these things wouldn't work? Are those things implemented in the default web worker, so that implementing my own web worker would bypass them? Or do they happen outside the web worker, and would therefore impact custom results that I fetch on my own?

Thanks for your help.

[squidfunk]

I'm going to start experimenting with custom search a bit, but I'd like to be certain that my understanding of this feature is correct before I get too far into it...

Am I correct that a custom web worker could pass a search query (entered in the default search UI) to an external service to fetch search results—and then I could massage those results and pass them back to Material for MkDocs to render in its default search/results UI (as opposed to a UI provided by the third party)?

Yes, that's correct and the intended use case for a custom search implementation.

As one follow-on question: I'm not clear how this approach would play with other search-related features (tags, boosts, suggestions, highlighting, etc.)—but I assume these things wouldn't work?

As the section on custom search explains, you would just have to stick to the message structure which is completely described by the typings (i.e. SearchMessage, and SearchResult). Note that Insiders (which you're probably using) added some extensions to those typings.

Are those things implemented in the default web worker, so that implementing my own web worker would bypass them? Or do they happen outside the web worker, and would therefore impact custom results that I fetch on my own?

While search query transformation is executed before passing the search query to the web worker, the actual search is carried out in the web worker. This includes the preparation and post-processing of search results before sending them back to the main thread. Thus, you would need to handle this yourself, but it's probably custom to any other search index implementation than lunr anyway, so probably mandatory.

Tip: you could set a breakpoint and trace the search query through the internals of the web worker.

I hope that clears things up. If you encounter any roadblocks, feel free to reach out. Furthermore, if we can improve the documentation on implementing custom search, a PR is always welcome.