Skip to content
Return to: MkDocs-MaterialX Start Page

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).

Back to: #Advanced-Configuration

Configuration⚓︎

Built-in Search Plugin⚓︎

The built-in search plugin integrates seamlessly with Material for MkDocs, adding multilingual client-side search with lunr and lunr-languages. It's enabled by default, but must be re-added to mkdocs.yml when other plugins are used:

plugins:
  - search

For a list of all settings, please consult the plugin documentation.

Search Suggestions⚓︎

When search suggestions are enabled, the search will display the likeliest completion for the last word which can be accepted with the Right key. Add the following lines to mkdocs.yml:

theme:
  features:
    - search.suggest

Searching for search su yields search suggestions as a suggestion.

Search Highlighting⚓︎

When search highlighting is enabled and a user clicks on a search result, Material for MkDocs will highlight all occurrences after following the link. Add the following lines to mkdocs.yml:

theme:
  features:
    - search.highlight

Searching for code blocks highlights all occurrences of both terms.

Search Sharing⚓︎

When search sharing is activated, a share button is rendered next to the reset button, which allows to deep link to the current search query and result. Add the following lines to mkdocs.yml:

theme:
  features:
    - search.share

When a user clicks the share button, the URL is automatically copied to the clipboard.

Usage⚓︎

Search Boosting⚓︎

Search Boosting

Pages can be boosted in search with the front matter search.boost property, which will make them rank higher. Add the following lines at the top of a Markdown file:

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

# Page title
...
  1. 🧘‍♀️ When boosting pages, be gentle and start with low values.
---
search:
  boost: 0.5
---

# Page title
...

Search Exclusion⚓︎

Search Exclusion

Pages can be excluded from search with the front matter search.exclude property, removing them from the index. Add the following lines at the top of a Markdown file:

---
search:
  exclude: true
---

# Page title
...

Excluding Sections⚓︎

Excluding Sections

When Attribute Lists is enabled, specific sections of pages can be excluded
from search by adding the data-search-exclude pragma after a Markdown
heading:

# Page title

## Section 1

The content of this section is included

## Section 2 { data-search-exclude }

The content of this section is excluded

{
  ...
  "docs": [
    {
      "location":"page/",
      "text":"",
      "title":"Document title"
    },
    {
      "location":"page/#section-1",
      "text":"<p>The content of this section is included</p>",
      "title":"Section 1"
    }
  ]
}

Excluding Blocks⚓︎

Excluding Blocks

When Attribute Lists is enabled, specific sections of pages can be excluded from search by adding the data-search-exclude pragma after a Markdown inline- or block-level element:

# Page title

The content of this block is included

The content of this block is excluded
{ data-search-exclude }

{
  ...
  "docs": [
    {
      "location":"page/",
      "text":"<p>The content of this block is included</p>",
      "title":"Document title"
    }
  ]
}

Back to: #Advanced-Configuration