Search¶

The built-in search plugin provides client-side search inside the browser and is implemented using lunr.js which includes stemmers for the English language by default, while stemmers for other languages are included with lunr-languages, both of which are integrated with this theme.

Make search work offline

While search will not work for the file:// protocol, as web workers and the use of XMLHTTPRequest are both blocked by modern browsers for security reasons, the localsearch plugin and @squidfunk's iframe-worker polyfill add support for cases where this is a mandatory requirement, e.g., for offline use.

Installation¶

The search plugin is a built-in plugin, and thus doesn't need to be installed.

Configuration¶

Add the following lines to mkdocs.yml:

plugins:
  - search

Language¶

Default: best match for theme.language, automatically set

Material for MkDocs selects the (best-)matching stemmer for the given theme language. Multilingual search can be enabled in mkdocs.yml by explicitly defining the search language(s):

plugins:
  - search:
      lang:
        - en
        - de
        - ru

The following language codes are supported:

Only specify the languages you really need

Be aware that including support for other languages increases the general JavaScript payload by around 20kb (before gzip) and by another 15-30kb per language.

Tokenization¶

Default: [\s\-]+

The separator for tokenization can be customized which makes it possible to index parts of words that are separated by - or .:

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

Prebuilding ¶

Default: false

MkDocs can generate a prebuilt index of all pages during build time, which provides performance improvements at the cost of more bandwidth. This may be beneficial for large documentation projects that are served with appropriate HTTP headers (e.g. Content-Encoding: gzip).

Material for MkDocs 5 finally brings experimental support for prebuilt indexes which can be enabled by adding the following lines to mkdocs.yml:

plugins:
  - search:
      prebuild_index: true

Usage¶

When enabled, a search bar is shown in the header.