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

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

Exclude from Search¶

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¶

Check if search plugin is enabled
Verify JavaScript is not blocked
Check browser console for errors
Ensure index files are generated

Poor Results¶

Review separator configuration
Check language settings
Verify content is indexed
Test different pipeline options

Performance Issues¶

Enable prebuild_index
Reduce indexed content
Optimize separator regex
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