Custom Search Worker setting is ignored #2973

https://github.com/squidfunk/mkdocs-material/issues/2973

xvandish opened on Aug 26, 2021 Contribution guidelines

I’ve read the contribution guidelines and wholeheartedly agree I’ve found a bug and checked that …

… the problem doesn’t occur with the mkdocs or readthedocs themes

… the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css

… the documentation does not mention anything about my problem

… there are no open or closed issues that are related to my problem Description As discussed in #2972, at the moment custom search does not work the way it’s described in the documentation here.

The worker used to implement search is not configurable in the way thats described by the documentation, which is to override the config block like so:

{% block config %} {{ super() }}

Expected behaviour I would expect the following block of code set in overrides/main.html

{% block config %} {{ super() }} {% endblock %} to load a worker at the path overrides/awesomeWorker.js and have the search html input pass messages to it for consumption and and processing.

Actual behaviour The worker mentioned in the config block is not called/passed messages by the search input, so effectively nothing happens.

Steps to reproduce setup a barebones mkdocs repo however you want (mkdocs new) add the search plugin in mkdocs.yaml. How-to is described here create a directory overrides set overrides as the custom_dir by setting custom_dir: overrides in mkdocs.yml under the theme block. How-to described here here Add a main.html file in the overrides directory. Set it’s file contents to: {% extends “base.html” %}

{% block htmltitle %}

Lorem ipsum dolor sit amet

{% endblock %}

{% block config %} {{ super() }} {% endblock %} Add a worker.js file in the overrides directory. Set its file contents to: console.log(‘whats going on’)

export async function handler(message) { console.log({ message }) }

addEventListener(“message”, async ev => { postMessage(await handler(ev.data)) }) Now type something in the search. You should see the default search.*.js worker still loaded and working in the background, instead of our custom worker.

Package versions Python: 3.9 MkDocs: 1.2.2 Material: 7.2.4 Configuration site_name: My Docs theme: name: material custom_dir: overrides plugins:

  • search System information Operating system: Mac OS Catalina (10.15.7) Browser: Google Chrome (92.0.4515.131) Activity xvandish xvandish commented on Aug 26, 2021 xvandish on Aug 26, 2021 · edited by xvandish Author I’m happy to contribute and help out, but I may not be able to do any work until this weekend or next.

Also, I understand the documented implementation of custom search may no longer how you’d like to go about this - things change all the time.

squidfunk added bug Issue reports a bug on Aug 26, 2021 squidfunk squidfunk commented on Aug 29, 2021 squidfunk on Aug 29, 2021 · edited by squidfunk Owner Okay, so I’ve managed to set aside some time to look into this. Here are some thoughts:

Search plugin dependency Search index Although it should be possible to define a custom search worker to completely alter the search behaviour, Material for MkDocs will by default always load search_index.json which is generated from the search plugin. The idea behind this is that we will always want to allow to build a client-side search from the MkDocs output, which depends on this very file.

The search_index.json is loaded here if the author did not provide a custom search index through __search.index, which is currently undocumented as it’s more or less a silent contract with the localsearch plugin:

mkdocs-material/src/assets/javascripts/bundle.ts

Lines 100 to 104 in 2d411a2

const index$ = document.forms.namedItem(“search”)
? __search?.index || requestJSON(
new URL(“search/search_index.json”, config.base)
)
NEVER If the search index should not be loaded, it can just be set to a Promise via __search.index, returning an object which follows the structure in search_index.json, as this is demanded by the setupSearchWorker function, which also adds some options (e.g. whether suggestions should be generated) before sending it to the search worker. From analyzing the control flow, the minimal “fake” search_index.json should look something like (untested):

{ “config”: { “lang”: [] }, “docs”: [] } Search form Note that the search form is only available if the search plugin is defined:

mkdocs-material/src/partials/header.html

Lines 132 to 139 in 2d411a2

{% if “search” in config[“plugins”] %}

{% include “partials/search.html” %} {% endif %} While the search plugin might not be necessary for external third-party search, it’s easier to check from a template perspective. If the search box should be shown regardless of the presence of the search plugin, omitting the need to build the search index at all, the partial can be overridden by using theme extension.

Search worker override So, now, to allow a custom search worker given all the constraints outlined before, I think that it’s okay to add the worker option back to the global __search override, although naming is slightly inconsistent with the config.search value passed to the JavaScript via the __config JSON in the template:

mkdocs-material/src/base.html

Lines 364 to 370 in 2d411a2

{%- set app = { “base”: base_url, “features”: features, “translations”: {}, “search”: “assets/javascripts/workers/search.js” | url, “version”: config.extra.version or None } -%} I’ve added it back in 441381b.

On a side note, please understand that we cannot provide further support for implementing a custom search worker beyond what’s already listed in the documentation. The inline documentation is pretty extensive and you’re invited to open further discussions to ask other users for help on a custom implementation. If you, however, run into another behaviour which is inconsistent with what is listed in the documentation, feel free to create another issue.

squidfunk added resolved Issue is resolved, yet unreleased if open on Aug 29, 2021 squidfunk squidfunk commented on Sep 2, 2021 squidfunk on Sep 2, 2021 Owner Released as part of 7.2.6.

squidfunk closed this as completedon Sep 2, 2021

Updated: