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
:
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:
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:
Features: - Highlights all occurrences - Works in page content after navigation - Preserves highlighting during session - Clear highlighting with Esc
Search Sharing¶
Enable shareable search URLs:
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:
Multiple Languages¶
For multilingual sites:
Language-Specific Options¶
Search Pipeline¶
Tokenization¶
Configure how text is split into tokens:
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:
Exclude from Search¶
Hide pages from search:
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 termterm*
- Prefix matchingtitle: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:
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¶
Accessibility¶
Search includes:
- ARIA labels and roles
- Keyboard navigation
- Screen reader announcements
- Focus management
- High contrast support