0
# Search Plugin
1

2
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.
3

4
## Capabilities
5

6
### Basic Search Setup
7

8
Core search configuration that enables full-text search functionality.
9

10
```yaml { .api }
11
plugins:
12
  - material/search:
13
      enabled: true              # Enable search plugin (default: true)
14
      lang: en                   # Search language (default: en)
15
      separator: '[\s\-\.]+'     # Word separator pattern
16
```
17

18
### Language Configuration
19

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

22
```yaml { .api }
23
plugins:
24
  - material/search:
25
      lang:
26
        - en                     # Single language
27
        - de
28
        - fr
29
      # Or single language
30
      lang: en
31
```
32

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

35
### Search Pipeline Configuration
36

37
Customizable text processing pipeline for search indexing and query processing.
38

39
```yaml { .api }
40
plugins:
41
  - material/search:
42
      pipeline:
43
        - stemmer              # Word stemming
44
        - stopWordFilter       # Remove common words
45
        - trimmer             # Trim whitespace
46
```
47

48
**Pipeline Options**:
49
- `stemmer`: Reduces words to root form
50
- `stopWordFilter`: Removes common stop words
51
- `trimmer`: Trims leading/trailing whitespace
52

53
### Advanced Search Options
54

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

57
```yaml { .api }
58
plugins:
59
  - material/search:
60
      # Chinese language support
61
      jieba_dict: dict.txt       # Chinese word segmentation dictionary
62
      jieba_dict_user: user_dict.txt  # User-defined dictionary
63
```
64

65
**Note**: Options like `indexing`, `min_search_length`, and `prebuild_index` are deprecated and no longer supported.
66

67
## Usage Examples
68

69
### Basic Search
70

71
```yaml
72
plugins:
73
  - material/search
74
```
75

76
### Multi-language Search
77

78
```yaml
79
plugins:
80
  - material/search:
81
      lang:
82
        - en
83
        - de
84
        - ja
85
      separator: '[\s\-\.\u3000]+'  # Include Japanese separator
86
```
87

88
### Optimized Search Pipeline
89

90
```yaml
91
plugins:
92
  - material/search:
93
      lang: en
94
      pipeline:
95
        - stemmer
96
        - stopWordFilter
97
        - trimmer
98
```
99

100
### Chinese Language Support
101

102
```yaml
103
plugins:
104
  - material/search:
105
      lang: zh
106
      jieba_dict: jieba_dict.txt
107
      jieba_dict_user: user_dict.txt
108
      separator: '[\s\u3000]+'
109
```
110

111
### Performance Optimized
112

113
```yaml
114
plugins:
115
  - material/search:
116
      lang: en
117
      pipeline:
118
        - trimmer
119
        - stopWordFilter
120
```
121

122
## Theme Integration
123

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

126
### Search Features in Theme
127

128
```yaml
129
theme:
130
  name: material
131
  features:
132
    - search.highlight         # Highlight search terms in results
133
    - search.share            # Share search results via URL
134
    - search.suggest          # Show search suggestions
135
```
136

137
### Search Keyboard Shortcuts
138

139
Default keyboard shortcuts for search functionality:
140
- `F` or `/`: Focus search input
141
- `Escape`: Clear search
142
- `Enter`: Navigate to first result
143
- `Arrow keys`: Navigate results
144

145
## Search Index Structure
146

147
The plugin generates a searchable index with the following structure:
148

149
```javascript { .api }
150
{
151
  "config": {
152
    "lang": ["en"],
153
    "separator": "[\\s\\-\\.]+"
154
  },
155
  "docs": [
156
    {
157
      "location": "path/to/page/",
158
      "title": "Page Title",
159
      "text": "Page content..."
160
    }
161
  ]
162
}
163
```
164

165
## Plugin API
166

167
```python { .api }
168
class SearchPlugin(BasePlugin[SearchConfig]):
169
    """Search plugin for creating searchable documentation index."""
170
    
171
    def on_startup(self, *, command, dirty):
172
        """Initialize search plugin on startup."""
173
    
174
    def on_config(self, config):
175
        """Configure search plugin settings."""
176
    
177
    def on_page_context(self, context, *, page, config, nav):
178
        """Add search context to page rendering."""
179
    
180
    def on_post_build(self, *, config):
181
        """Generate search index after site build."""
182
    
183
    def on_serve(self, server, *, config, builder):
184
        """Configure development server for search."""
185
```
186

187
## Search Configuration Schema
188

189
```python { .api }
190
class SearchConfig(Config):
191
    """Configuration options for the search plugin."""
192
    
193
    enabled = Type(bool, default=True)
194
    lang = Optional(LangOption())  # Language configuration
195
    separator = Optional(Type(str))  # Word separator pattern
196
    pipeline = Optional(ListOfItems(Choice(['stemmer', 'stopWordFilter', 'trimmer'])))
197
    jieba_dict = Optional(Type(str))  # Chinese word segmentation dictionary
198
    jieba_dict_user = Optional(Type(str))  # User-defined dictionary
199
```