Skip to content

Search

Material for MkDocs includes a powerful client-side search implementation that provides instant results without requiring a server.

Overview

The search functionality includes:

  • Instant search - Results appear as you type
  • Search suggestions - Autocomplete functionality
  • Highlighting - Matched terms highlighted in results
  • Keyboard navigation - Full keyboard support
  • Search sharing - Share search URLs
  • Offline support - Works without internet connection

Configuration

Basic Setup

Search is enabled by default. Configure in mkdocs.yml:

plugins:
  - search:
      lang: en

Advanced Configuration

plugins:
  - search:
      lang: en
      separator: '[\s\-,:!=\[\]()/\"]+|(?!\b)(?=[A-Z][a-z])'
      pipeline:
        - stemmer
        - stopWordFilter
        - trimmer

theme:
  features:
    - search.suggest      # Enable suggestions
    - search.highlight    # Highlight search terms
    - search.share        # Enable search sharing

Features

Search Suggestions

Enable autocomplete suggestions:

theme:
  features:
    - search.suggest

This provides: - Dropdown suggestions while typing - Most relevant matches first - Keyboard navigation through suggestions - Quick access to popular searches

Search Highlighting

Highlight search terms in results:

theme:
  features:
    - search.highlight

Features: - Highlights all occurrences - Works in page content after navigation - Preserves highlighting during session - Clear highlighting with Esc

Search Sharing

Enable shareable search URLs:

theme:
  features:
    - search.share

This adds: - Share button in search dialog - Direct URLs to search results - Pre-populated search on page load - Social media sharing support

Language Support

Single Language

Configure language-specific search:

plugins:
  - search:
      lang: en  # or: de, es, fr, it, ja, pt, ru, etc.

Multiple Languages

For multilingual sites:

plugins:
  - search:
      lang:
        - en
        - de
        - fr

Language-Specific Options

plugins:
  - search:
      lang: ja
      separator: '[\s\-\.]+'  # Japanese-specific separator

Search Pipeline

Tokenization

Configure how text is split into tokens:

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()/\"]+|(?!\b)(?=[A-Z][a-z])'

This regex: - Splits on whitespace and punctuation - Handles camelCase and PascalCase - Preserves acronyms - Supports special characters

Pipeline Stages

Configure text processing pipeline:

plugins:
  - search:
      pipeline:
        - stemmer         # Reduce words to stems
        - stopWordFilter  # Remove common words
        - trimmer         # Remove extra whitespace

Available stages: - stemmer - Word stemming (language-aware) - stopWordFilter - Remove stop words - trimmer - Trim whitespace

Customization

Search Weight

Boost certain pages in results:

# In page frontmatter
---
search:
  boost: 2.0  # Double the relevance
---

Hide pages from search:

# In page frontmatter
---
search:
  exclude: true
---

Custom Search Index

Override search index fields:

plugins:
  - search:
      fields:
        - title^2      # Title with 2x weight
        - tags^1.5     # Tags with 1.5x weight
        - text         # Body text

Search Interface

Keyboard Shortcuts

Action Shortcut
Open search F, S, /
Navigate results Up, Down
Select result Enter
Close search Esc
Clear search Ctrl+Backspace

Search Syntax

Users can use special syntax:

  • "exact phrase" - Exact phrase matching
  • +required - Must include term
  • -excluded - Must not include term
  • term* - Prefix matching
  • title:keyword - Search in title only

Styling

Custom CSS

/* docs/assets/stylesheets/search.css */

/* Search input styling */
.md-search__input {
  background-color: var(--md-default-bg-color);
  border-radius: 0.2rem;
}

/* Search result styling */
.md-search-result__item {
  padding: 0.8rem;
  border-radius: 0.2rem;
}

.md-search-result__item:hover {
  background-color: var(--md-default-fg-color--lightest);
}

/* Highlight styling */
.md-search-result mark {
  background-color: var(--md-accent-fg-color--transparent);
  color: var(--md-accent-fg-color);
  font-weight: 700;
}

/* Search icon */
.md-search__icon[for="__search"] {
  color: var(--md-default-fg-color--light);
}

Dark Mode Support

[data-md-color-scheme="slate"] {
  /* Dark mode search styling */
  .md-search__input {
    background-color: var(--md-code-bg-color);
  }

  .md-search-result__item:hover {
    background-color: var(--md-code-bg-color);
  }
}

Performance Optimization

Index Size

Reduce search index size:

plugins:
  - search:
      prebuild_index: true      # Build index at build time
      min_search_length: 3      # Minimum query length

Lazy Loading

Search index loads on demand: - Initial page load is faster - Index loads when search is activated - Cached for subsequent searches

Large Sites

For documentation with 1000+ pages:

plugins:
  - search:
      prebuild_index: true
      workers: 4  # Parallel processing

Integration

With Other Plugins

Search indexes content from: - mkdocs-jupyter notebooks - mkdocstrings API documentation - Blog posts - Generated content

Custom Content

Add searchable metadata:

---
tags:
  - configuration
  - advanced
  - search
---

# Page Title

This content is searchable including the tags.

Advanced Features

Search Analytics

Track search queries (requires custom JavaScript):

// docs/assets/javascripts/search-analytics.js
document.addEventListener("DOMContentLoaded", function() {
  const searchInput = document.querySelector(".md-search__input");

  searchInput.addEventListener("change", function(e) {
    // Send to analytics
    gtag("event", "search", {
      search_term: e.target.value
    });
  });
});

Custom Search Provider

Replace with external search:

plugins:
  - search:
      enabled: false  # Disable built-in search

extra_javascript:
  - assets/javascripts/algolia-search.js

Best Practices

1. Content Optimization

Write searchable content:

  • Use descriptive headings
  • Include relevant keywords
  • Write clear summaries
  • Use consistent terminology

2. Metadata

Add search metadata:

---
title: Complete Search Guide
description: Everything about search functionality
tags: [search, configuration, features]
---

3. Structure

Organize for findability:

  • Clear page titles
  • Descriptive URLs
  • Logical hierarchy
  • Cross-references

4. Testing

Test search functionality:

  • Common queries return expected results
  • Typos are handled gracefully
  • Performance is acceptable
  • Mobile experience is good

Troubleshooting

Search Not Working

  1. Check if search plugin is enabled
  2. Verify JavaScript is not blocked
  3. Check browser console for errors
  4. Ensure index files are generated

Poor Results

  1. Review separator configuration
  2. Check language settings
  3. Verify content is indexed
  4. Test different pipeline options

Performance Issues

  1. Enable prebuild_index
  2. Reduce indexed content
  3. Optimize separator regex
  4. Use search exclusions

Examples

Configuration for Technical Docs

plugins:
  - search:
      lang: en
      separator: '[\s\-\._,:!=\[\]()/\"]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
      pipeline:
        - stemmer
        - stopWordFilter
      fields:
        - title^3
        - text
        - tags^2

Multilingual Configuration

plugins:
  - search:
      lang:
        - en
        - es
        - fr
      separator: '[\s\-,:!=\[\]()/\"]+|(?!\b)(?=[A-Z][a-z])'

Accessibility

Search includes:

  • ARIA labels and roles
  • Keyboard navigation
  • Screen reader announcements
  • Focus management
  • High contrast support

See Also