mkdocs-material/docs/plugins/search.md

template
overrides/main.html

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.

!!! tip "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][4] plugin and @squidfunk's [iframe-worker][5]
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:

• ar / Arabic
• da / Danish
• du / Dutch
• en / English
• fi / Finnish
• fr / French
• de / German
• hu / Hungarian
• it / Italian
• ja / Japanese
• no / Norwegian
• pt / Portuguese
• ro / Romanian
• ru / Russian
• es / Spanish
• sv / Swedish
• th / Thai
• tr / Turkish
• vi / Vietnamese

!!! warning "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.