tessl/pypi-mkdocs-material

Material Design theme for MkDocs with built-in plugins for blogs, search, social cards, and privacy compliance

—

Pending

Overview

Eval results

Files

Search Plugin

Name: tessl/pypi-mkdocs-material
Author: tessl

Advanced search functionality providing instant client-side search across documentation with language support, search highlighting, suggestions, and configurable search pipeline. The search plugin creates a searchable index for fast, responsive documentation search.

Capabilities

Basic Search Setup

Core search configuration that enables full-text search functionality.

plugins:
  - material/search:
      enabled: true              # Enable search plugin (default: true)
      lang: en                   # Search language (default: en)
      separator: '[\s\-\.]+'     # Word separator pattern

Language Configuration

Multi-language search support with language-specific stemming and stop words.

plugins:
  - material/search:
      lang:
        - en                     # Single language
        - de
        - fr
      # Or single language
      lang: en

Supported Languages: ar, da, de, du, en, es, fi, fr, hu, it, ja, no, pt, ro, ru, sv, th, tr, zh

Search Pipeline Configuration

Customizable text processing pipeline for search indexing and query processing.

plugins:
  - material/search:
      pipeline:
        - stemmer              # Word stemming
        - stopWordFilter       # Remove common words
        - trimmer             # Trim whitespace

Pipeline Options:

stemmer: Reduces words to root form
stopWordFilter: Removes common stop words
trimmer: Trims leading/trailing whitespace

Advanced Search Options

Fine-tuned search behavior including Chinese language support and content processing.

plugins:
  - material/search:
      # Chinese language support
      jieba_dict: dict.txt       # Chinese word segmentation dictionary
      jieba_dict_user: user_dict.txt  # User-defined dictionary

Note: Options like indexing, min_search_length, and prebuild_index are deprecated and no longer supported.

Usage Examples

Basic Search

plugins:
  - material/search

Multi-language Search

plugins:
  - material/search:
      lang:
        - en
        - de
        - ja
      separator: '[\s\-\.\u3000]+'  # Include Japanese separator

Optimized Search Pipeline

plugins:
  - material/search:
      lang: en
      pipeline:
        - stemmer
        - stopWordFilter
        - trimmer

Chinese Language Support

plugins:
  - material/search:
      lang: zh
      jieba_dict: jieba_dict.txt
      jieba_dict_user: user_dict.txt
      separator: '[\s\u3000]+'

Performance Optimized

plugins:
  - material/search:
      lang: en
      pipeline:
        - trimmer
        - stopWordFilter

Theme Integration

The search plugin integrates with theme features for enhanced search experience.

Search Features in Theme

theme:
  name: material
  features:
    - search.highlight         # Highlight search terms in results
    - search.share            # Share search results via URL
    - search.suggest          # Show search suggestions

Search Keyboard Shortcuts

Default keyboard shortcuts for search functionality:

F or /: Focus search input
Escape: Clear search
Enter: Navigate to first result
Arrow keys: Navigate results

Search Index Structure

The plugin generates a searchable index with the following structure:

{
  "config": {
    "lang": ["en"],
    "separator": "[\\s\\-\\.]+"
  },
  "docs": [
    {
      "location": "path/to/page/",
      "title": "Page Title",
      "text": "Page content..."
    }
  ]
}

Plugin API

class SearchPlugin(BasePlugin[SearchConfig]):
    """Search plugin for creating searchable documentation index."""
    
    def on_startup(self, *, command, dirty):
        """Initialize search plugin on startup."""
    
    def on_config(self, config):
        """Configure search plugin settings."""
    
    def on_page_context(self, context, *, page, config, nav):
        """Add search context to page rendering."""
    
    def on_post_build(self, *, config):
        """Generate search index after site build."""
    
    def on_serve(self, server, *, config, builder):
        """Configure development server for search."""

Search Configuration Schema

class SearchConfig(Config):
    """Configuration options for the search plugin."""
    
    enabled = Type(bool, default=True)
    lang = Optional(LangOption())  # Language configuration
    separator = Optional(Type(str))  # Word separator pattern
    pipeline = Optional(ListOfItems(Choice(['stemmer', 'stopWordFilter', 'trimmer'])))
    jieba_dict = Optional(Type(str))  # Chinese word segmentation dictionary
    jieba_dict_user = Optional(Type(str))  # User-defined dictionary

Install with Tessl CLI