Skip to content

Setting up site search

MaterialX 10.2.0 fully refactors the search module with a brand-new architecture, greatly improving search quality and indexing efficiency.

It supports multi-provider mode, chunked indexing, on-demand loading, index compression, multilingual search and cross-domain search. It is suitable for various complex scenarios and large-scale sites, and can handle sites with more than 100,000 pages.

Pagefind is the default provider. You may switch back to the original Lunr when using it in an offline environment (opened via the file:// protocol).

Configuration

Built-in search plugin

10.2.0

The built-in search plugin adds client-side search without requiring a hosted search service. It's enabled by default, but must be re-added to mkdocs.yml when other plugins are configured:

plugins:
  - search

Pagefind creates a chunked static index after the site is built and loads only the index data needed for each query.

plugins:
  - offline
  - search:
      provider: lunr

Together with the offline plugin, Lunr packages the search index as a script and can therefore search a site opened directly from the local filesystem.

Both providers use the same MaterialX search interface. Provider-specific settings are nested under pagefind and lunr, so changing providers doesn't require changing the theme or search UI. For the complete mkdocs.yml structure and all available settings, see the plugin documentation.

Search suggestions

7.2.0

When search suggestions are enabled, the search displays the likeliest completion for the last word, which can be accepted with the Right key. Suggestions are currently available with the Lunr provider:

plugins:
  - search:
      provider: lunr

theme:
  features:
    - search.suggest

Searching for search su yields search suggestions as a suggestion.

Search highlighting

7.2.0

When search highlighting is enabled and a user follows a search result, MaterialX highlights all occurrences of the search terms on the destination page. This feature works with both providers:

theme:
  features:
    - search.highlight

Searching for code blocks highlights all occurrences of both terms.

Search sharing

7.2.0

When search sharing is enabled, a share button is rendered next to the reset button. It copies a deep link to the current query and results to the clipboard:

theme:
  features:
    - search.share

Usage

Search exclusion

9.0.0

Pages can be excluded from either provider with the front matter search.exclude property:

---
search:
  exclude: true
---

# Page title
...

Use the built-in meta plugin to apply the same property to a complete folder and all of its subfolders. Excluding only part of a page is provider-specific: Pagefind uses data-pagefind-ignore, while Lunr uses data-search-exclude. See Pagefind content exclusion and Lunr content exclusion for examples.

Search boosting

8.3.0

Lunr pages can be boosted with the front matter search.boost property. Use values above 1 to rank a page up and values below 1 to rank it down:

---
search:
  boost: 2 # (1)!
---

# Page title
...
  1. When boosting pages, start with small adjustments.
---
search:
  boost: 0.5
---

# Page title
...

Pagefind provides its own content weighting and browser-side ranking controls. The search plugin documentation explains how Pagefind options fit into mkdocs.yml.