1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-22 20:36:02 +01:00
mkdocs-material/docs/setup/setting-up-site-search.md
2023-08-21 18:54:53 +02:00

445 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
search:
boost: 1.05
---
# Setting up site search
Material for MkDocs provides an excellent client-side search implementation,
omitting the need for the integration of third-party services, which might
not be compliant with privacy regulations. Moreover, search even works
[offline], allowing users to download your documentation.
[offline]: building-for-offline-usage.md
## Configuration
### Built-in search plugin
[:octicons-tag-24: 0.1.0][Search support] ·
:octicons-cpu-24: Plugin
The built-in search plugin integrates seamlessly with Material for MkDocs,
adding multilingual client-side search with [lunr] and [lunr-languages]. It's
enabled by default, but must be re-added to `mkdocs.yml` when other plugins
are used:
``` yaml
plugins:
- search
```
The following configuration options are supported:
[`lang`](#+search.lang){ #+search.lang }
: :octicons-milestone-24: Default: _automatically set_ This option allows
to include the language-specific stemmers provided by [lunr-languages].
Note that Material for MkDocs will set this automatically based on the
[site language], but it may be overridden, e.g. to support multiple
languages:
=== "A single language"
``` yaml
plugins:
- search:
lang: en
```
=== "Multiple languages"
``` yaml
plugins:
- search:
lang: # (1)!
- en
- de
```
1. Be aware that including support for other languages increases the
general JavaScript payload by around 20kb (before `gzip`) and by
another 15-30kb per language.
The following languages are 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>
Material for MkDocs goes to great lengths to support languages that are not
part of this list by automatically falling back to the stemmer yielding the
best result.
[`separator`](#+search.separator){ #+search.separator }
: :octicons-milestone-24: Default: _automatically set_ The separator for
indexing and query tokenization can be customized, making it possible to
index parts of words separated by other characters than whitespace and `-`,
e.g. by including `.`:
``` yaml
plugins:
- search:
separator: '[\s\-\.]+'
```
With :octicons-tag-24: 9.0.0, a faster and more flexible tokenizer method
is shipped, allowing for __tokenizing with lookahead__, which yields more
influence on the way documents are indexed. As a result, we use the
following separator setting for this site's search:
``` yaml
plugins:
- search:
separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
```
Broken into its parts, the 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`.
[:octicons-arrow-right-24: Read more on tokenizing case changes]
[tokenize case changes]
=== "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.
[:octicons-arrow-right-24: Read more on tokenizing version numbers]
[tokenize version numbers]
=== "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 `&lt;` and `&gt;`. Adding this
subexpression to the separator allows for just that.
[:octicons-arrow-right-24: Read more on tokenizing HTML/XML tags]
[tokenize html-xml tags]
[Search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[lunr]: https://lunrjs.com
[lunr-languages]: https://github.com/MihaiValentin/lunr-languages
[lunr's default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
[site language]: changing-the-language.md#site-language
[words are split at case changes]: ?q=searchHighlight
[preserve version strings]: ?q=9.0.0
[tokenize case changes]: ../blog/posts/search-better-faster-smaller.md#case-changes
[tokenize version numbers]: ../blog/posts/search-better-faster-smaller.md#version-numbers
[tokenize html-xml tags]: ../blog/posts/search-better-faster-smaller.md#htmlxml-tags
#### Chinese language support
[:octicons-tag-24: 9.2.0][Chinese language support] ·
:octicons-beaker-24: Experimental
In order to add support for Chinese languages to the [built-in search plugin],
install the text segmentation library [jieba] via `pip`, and the plugin will
run all text through the segmenter:
``` sh
pip install jieba
```
The following configuration options are available:
[`jieba_dict`](#+search.jieba_dict){ #+search.jieba_dict }
: :octicons-milestone-24: Default: _none_ This option allows for specifying
a [custom dictionary] to be used by [jieba] for segmenting text, replacing
the default dictionary:
``` yaml
plugins:
- search:
jieba_dict: dict.txt # (1)!
```
1. The following alternative dictionaries are provided by [jieba]:
- [dict.txt.small] 占用内存较小的词典文件
- [dict.txt.big] 支持繁体分词更好的词典文件
[`jieba_dict_user`](#+search.jieba_dict_user){ #+search.jieba_dict_user }
: :octicons-milestone-24: Default: _none_ This option allows for specifying
an additional [user dictionary] to be used by [jieba] for segmenting text,
augmenting the default dictionary:
``` yaml
plugins:
- search:
jieba_dict_user: user_dict.txt
```
User dictionaries can be used for tuning the segmenter to preserve
technical terms.
[Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
[chinese search]: ../blog/posts/chinese-search-support.md
[jieba]: https://pypi.org/project/jieba/
[built-in search plugin]: #built-in-search-plugin
[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
[user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
### Search suggestions
[:octicons-tag-24: 7.2.0][Search suggestions support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When search suggestions are enabled, the search will display the likeliest
completion for the last word which can be accepted with the ++arrow-right++ key.
Add the following lines to `mkdocs.yml`:
``` yaml
theme:
features:
- search.suggest
```
Searching for [:octicons-search-24: search su][Search suggestions example]
yields ^^search suggestions^^ as a suggestion.
[Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search suggestions example]: ?q=search+su
### Search highlighting
[:octicons-tag-24: 7.2.0][Search highlighting support] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When search highlighting is enabled and a user clicks on a search result,
Material for MkDocs will highlight all occurrences after following the link.
Add the following lines to `mkdocs.yml`:
``` yaml
theme:
features:
- search.highlight
```
Searching for [:octicons-search-24: code blocks][Search highlighting example]
highlights all occurrences of both terms.
[Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
[Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
### Search sharing
[:octicons-tag-24: 7.2.0][Search sharing support] ·
:octicons-unlock-24: Feature flag
When search sharing is activated, a :material-share-variant: share button is
rendered next to the reset button, which allows to deep link to the current
search query and result. Add the following lines to `mkdocs.yml`:
``` yaml
theme:
features:
- search.share
```
When a user clicks the share button, the URL is automatically copied to the
clipboard.
[Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
## Usage
### Search boosting
[:octicons-tag-24: 8.3.0][boost support]
Pages can be boosted in search with the front matter `search.boost` property,
which will make them rank higher. Add the following lines at the top of a
Markdown file:
=== ":material-arrow-up-circle: Rank up"
``` yaml
---
search:
boost: 2 # (1)!
---
# Document title
...
```
1. :woman_in_lotus_position: When boosting pages, be gentle and start with
__low values__.
=== ":material-arrow-down-circle: Rank down"
``` yaml
---
search:
boost: 0.5
---
# Document title
...
```
[boost support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
### Search exclusion
[:octicons-tag-24: 9.0.0][exclusion support] ·
:octicons-beaker-24: Experimental
Pages can be excluded from search with the front matter `search.exclude`
property, removing them from the index. Add the following lines at the top of a
Markdown file:
``` yaml
---
search:
exclude: true
---
# Document title
...
```
[exclusion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
#### Excluding sections
When [Attribute Lists] is enabled, specific sections of pages can be excluded
from search by adding the `data-search-exclude` pragma after a Markdown
heading:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
## Section 1
The content of this section is included
## Section 2 { data-search-exclude }
The content of this section is excluded
```
=== ":octicons-codescan-16: `search_index.json`"
``` json
{
...
"docs": [
{
"location":"page/",
"text":"",
"title":"Document title"
},
{
"location":"page/#section-1",
"text":"<p>The content of this section is included</p>",
"title":"Section 1"
}
]
}
```
[Attribute Lists]: extensions/python-markdown.md#attribute-lists
#### Excluding blocks
When [Attribute Lists] is enabled, specific sections of pages can be excluded
from search by adding the `data-search-exclude` pragma after a Markdown
inline- or block-level element:
=== ":octicons-file-code-16: `docs/page.md`"
``` markdown
# Document title
The content of this block is included
The content of this block is excluded
{ data-search-exclude }
```
=== ":octicons-codescan-16: `search_index.json`"
``` json
{
...
"docs": [
{
"location":"page/",
"text":"<p>The content of this block is included</p>",
"title":"Document title"
}
]
}
```