mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-22 20:36:02 +01:00
428 lines
11 KiB
Markdown
428 lines
11 KiB
Markdown
---
|
||
title: Built-in search plugin
|
||
icon: material/magnify
|
||
---
|
||
|
||
# Built-in search plugin
|
||
|
||
The search plugin adds a search bar to the header, allowing users to search your
|
||
documentation. It's powered by [lunr.js], a lightweight full-text search engine
|
||
for the browser, elimininating the need for external services, and even works
|
||
when building [offline-capable documentation].
|
||
|
||
[lunr.js]: https://lunrjs.com/
|
||
[offline-capable documentation]: ../setup/building-for-offline-usage.md
|
||
|
||
## Objective
|
||
|
||
### How it works
|
||
|
||
The plugin scans the generated HTML and builds a search index from all pages and
|
||
sections by extracting the section titles and contents. It preserves some inline
|
||
formatting like code blocks and lists, but removes all other formatting, so the
|
||
search index is as small as possible.
|
||
|
||
When a user visits your site, the search index is shipped to the browser,
|
||
indexed with [lunr.js] and made available for fast and simple querying – no
|
||
server needed. This ensures that the search index is always up to date with
|
||
your documentation, yielding accurate results.
|
||
|
||
### When to use it
|
||
|
||
It's generally recommended to use the plugin, as interactive search functionality
|
||
is a vital part of every good documentation. Additionally, the plugin integrates
|
||
perfectly with several of the other [built-in plugins] that Material for MkDocs
|
||
offers:
|
||
|
||
<div class="grid cards" markdown>
|
||
|
||
- :material-connection: __[Built-in offline plugin][offline]__
|
||
|
||
---
|
||
|
||
The offline plugin adds support for building offline-capable documentation,
|
||
so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
|
||
file that can be downloaded.
|
||
|
||
---
|
||
|
||
__Your documentation can work without connectivity to the internet__
|
||
|
||
- :material-file-tree: __[Built-in meta plugin][meta]__
|
||
|
||
---
|
||
|
||
The meta plugin makes it easy to [boost][meta.search.boost] specific
|
||
sections in search results or to [exclude][meta.search.exclude] them
|
||
entirely from being indexed, giving more granular control over search.
|
||
|
||
---
|
||
|
||
__Simpler organization and management of search in different subsections__
|
||
|
||
</div>
|
||
|
||
[offline]: offline.md
|
||
[meta]: meta.md
|
||
[built-in plugins]: index.md
|
||
|
||
## Configuration
|
||
|
||
<!-- md:version 9.0.0 -->
|
||
<!-- md:plugin [search] – built-in -->
|
||
|
||
As with all [built-in plugins], getting started with the search plugin is
|
||
straightforward. Just add the following lines to `mkdocs.yml`, and your users
|
||
will be able to search your documentation:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search
|
||
```
|
||
|
||
The search plugin is built into Material for MkDocs and doesn't need to be
|
||
installed.
|
||
|
||
[search]: search.md
|
||
[built-in plugins]: index.md
|
||
|
||
### General
|
||
|
||
The following settings are available:
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.enabled -->
|
||
|
||
<!-- md:version 9.3.2 -->
|
||
<!-- md:default `true` -->
|
||
|
||
Use this setting to enable or disable the plugin when [building your project].
|
||
It's normally not necessary to specify this setting, but if you want to disable
|
||
the plugin, use:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search:
|
||
enabled: false
|
||
```
|
||
|
||
[building your project]: ../creating-your-site.md#building-your-site
|
||
|
||
### Search
|
||
|
||
The following settings are available for search:
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.lang -->
|
||
|
||
<!-- md:version 9.0.0 -->
|
||
<!-- md:default computed -->
|
||
|
||
Use this setting to specify the language of the search index, enabling [stemming]
|
||
support for other languages than English. The default value is automatically
|
||
computed from the [site language], but can be explicitly set to another language
|
||
or even multiple languages with:
|
||
|
||
=== "Set language"
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search:
|
||
lang: en
|
||
```
|
||
|
||
=== "Add further languages"
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search:
|
||
lang: # (1)!
|
||
- en
|
||
- de
|
||
```
|
||
|
||
1. Be aware that including support for further languages increases the
|
||
base JavaScript payload by around 20kb and by another 15-30kb per
|
||
language, all before `gzip`.
|
||
|
||
[stemming]: https://en.wikipedia.org/wiki/Stemming
|
||
[site language]: ../setup/changing-the-language.md#site-language
|
||
[lunr languages]: https://github.com/MihaiValentin/lunr-languages
|
||
|
||
Language support is provided by [lunr languages], a collection of
|
||
language-specific stemmers and stop words for [lunr.js] maintained by the
|
||
Open Source community.
|
||
|
||
---
|
||
|
||
The following languages are currently supported by [lunr languages]:
|
||
|
||
<div class="mdx-columns" markdown>
|
||
|
||
- `ar` – Arabic
|
||
- `da` – Danish
|
||
- `de` – German
|
||
- `du` – Dutch
|
||
- `en` – English
|
||
- `es` – Spanish
|
||
- `fi` – Finnish
|
||
- `fr` – French
|
||
- `hi` – Hindi
|
||
- `hu` – Hungarian
|
||
- `hy` – Armenian
|
||
- `it` – Italian
|
||
- `ja` – Japanese
|
||
- `kn` - Kannada
|
||
- `ko` – Korean
|
||
- `no` – Norwegian
|
||
- `pt` – Portuguese
|
||
- `ro` – Romanian
|
||
- `ru` – Russian
|
||
- `sa` – Sanskrit
|
||
- `sv` – Swedish
|
||
- `ta` – Tamil
|
||
- `te` – Telugu
|
||
- `th` – Thai
|
||
- `tr` – Turkish
|
||
- `vi` – Vietnamese
|
||
- `zh` – Chinese
|
||
|
||
</div>
|
||
|
||
If [lunr languages] doesn't provide support for the selected [site language],
|
||
the plugin falls back to another language that yields the best stemming results.
|
||
If you discover that the search results are not satisfactory, you can contribute
|
||
to [lunr languages] by adding support for your language.
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.separator -->
|
||
|
||
<!-- md:version 9.0.0 -->
|
||
<!-- md:default computed -->
|
||
|
||
Use this setting to specify the separator used to split words when building the
|
||
search index on the client side. The default value is automatically computed
|
||
from the [site language], but can also be explicitly set to another value with:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search:
|
||
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
|
||
```
|
||
|
||
Separators support [positive and negative lookahead assertions], which allows
|
||
for rather complex expressions that yield precise control over how words are
|
||
split when building the search index.
|
||
|
||
Broken into its parts, this separator induces the following behavior:
|
||
|
||
=== "Special characters"
|
||
|
||
```
|
||
[\s\-,:!=\[\]()"/]+
|
||
```
|
||
|
||
The first part of the expression inserts token boundaries for each
|
||
document before and after whitespace, hyphens, commas, brackets and
|
||
other special characters. If several of those special characters are
|
||
adjacent, they are treated as one.
|
||
|
||
=== "Case changes"
|
||
|
||
```
|
||
(?!\b)(?=[A-Z][a-z])
|
||
```
|
||
|
||
Many programming languages have naming conventions like `PascalCase` or
|
||
`camelCase`. By adding this subexpression to the separator,
|
||
[words are split at case changes], tokenizing the word `PascalCase`
|
||
into `Pascal` and `Case`.
|
||
|
||
=== "Version strings"
|
||
|
||
```
|
||
\.(?!\d)
|
||
```
|
||
|
||
When adding `.` to the separator, version strings like `1.2.3` are split
|
||
into `1`, `2` and `3`, which makes them undiscoverable via search. When
|
||
using this subexpression, a small lookahead is introduced which will
|
||
[preserve version strings] and keep them discoverable.
|
||
|
||
=== "HTML/XML tags"
|
||
|
||
```
|
||
&[lg]t;
|
||
```
|
||
|
||
If your documentation includes HTML/XML code examples, you may want to allow
|
||
users to find [specific tag names]. Unfortunately, the `<` and `>` control
|
||
characters are encoded in code blocks as `<` and `>`. Adding this
|
||
subexpression to the separator allows for just that.
|
||
|
||
[positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
|
||
[words are split at case changes]: ?q=searchHighlight
|
||
[preserve version strings]: ?q=9.0.0
|
||
[specific tag names]: ?q=script
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.pipeline -->
|
||
|
||
<!-- md:version 9.0.0 -->
|
||
<!-- md:default computed -->
|
||
<!-- md:flag experimental -->
|
||
|
||
Use this setting to specify the [pipeline functions] that are used to filter and
|
||
expand tokens after tokenizing them with the [`separator`][config.separator] and
|
||
before adding them to the search index. The default value is automatically
|
||
computed from the [site language], but can also be explicitly set with:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search:
|
||
pipeline:
|
||
- stemmer
|
||
- stopWordFilter
|
||
- trimmer
|
||
```
|
||
|
||
The following pipeline functions can be used:
|
||
|
||
- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`
|
||
- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.
|
||
- `trimmer` – Trim whitespace from tokens
|
||
|
||
[pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
|
||
|
||
### Segmentation
|
||
|
||
The plugin supports text segmentation of Chinese via [jieba], a popular
|
||
Chinese text segmentation library. Other languages like Japanese and Korean are
|
||
currently segmented on the client side, but we're considering to move this
|
||
functionality into the plugin in the future.
|
||
|
||
The following settings are available for segmentation:
|
||
|
||
[jieba]: https://pypi.org/project/jieba/
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.jieba_dict -->
|
||
|
||
<!-- md:version 9.2.0 -->
|
||
<!-- md:default none -->
|
||
<!-- md:flag experimental -->
|
||
|
||
Use this setting to specify a [custom dictionary] to be used by [jieba] for
|
||
segmenting text, replacing the default dictionary. [jieba] comes with
|
||
several dictionaries, which can be used with:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search:
|
||
jieba_dict: dict.txt
|
||
```
|
||
|
||
The following dictionaries are provided by [jieba]:
|
||
|
||
- [dict.txt.small] – 占用内存较小的词典文件
|
||
- [dict.txt.big] – 支持繁体分词更好的词典文件
|
||
|
||
The provided path is resolved from the root directory.
|
||
|
||
[custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
|
||
[dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
|
||
[dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.jieba_dict_user -->
|
||
|
||
<!-- md:version 9.2.0 -->
|
||
<!-- md:default none -->
|
||
<!-- md:flag experimental -->
|
||
|
||
Use this setting to specify an additional [user dictionary] to be used by
|
||
[jieba] for segmenting text, augmenting the default dictionary. User
|
||
dictionaries are ideal for tuning the segmenter:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- search:
|
||
jieba_dict_user: user_dict.txt
|
||
```
|
||
|
||
The provided path is resolved from the root directory.
|
||
|
||
[user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
|
||
|
||
## Usage
|
||
|
||
### Metadata
|
||
|
||
The following properties are available:
|
||
|
||
---
|
||
|
||
#### <!-- md:setting meta.search.boost -->
|
||
|
||
<!-- md:version 8.3.0 -->
|
||
<!-- md:flag metadata -->
|
||
<!-- md:default none -->
|
||
|
||
Use this property to increase or decrease the relevance of a page in the search
|
||
results, giving more weight to them. Use values above `1` to rank up and values
|
||
below `1` to rank down:
|
||
|
||
=== ":material-arrow-up-circle: Rank up"
|
||
|
||
``` yaml
|
||
---
|
||
search:
|
||
boost: 2 # (1)!
|
||
---
|
||
|
||
# Page title
|
||
...
|
||
```
|
||
|
||
1. When boosting pages, always start with low values.
|
||
|
||
=== ":material-arrow-down-circle: Rank down"
|
||
|
||
``` yaml
|
||
---
|
||
search:
|
||
boost: 0.5
|
||
---
|
||
|
||
# Page title
|
||
...
|
||
```
|
||
|
||
---
|
||
|
||
#### <!-- md:setting meta.search.exclude -->
|
||
|
||
<!-- md:version 9.0.0 -->
|
||
<!-- md:flag metadata -->
|
||
<!-- md:default none -->
|
||
|
||
Use this property to exclude a page from the search results. Note that this will
|
||
not only remove the page, but also all subsections of the page from the search
|
||
results:
|
||
|
||
``` yaml
|
||
---
|
||
search:
|
||
exclude: true
|
||
---
|
||
|
||
# Page title
|
||
...
|
||
```
|