配置站点搜索

Material for MkDocs 提供了一个出色的客户端搜索实现，省去了集成第三方服务的需求，这些服务可能不符合隐私规定。此外，搜索甚至可以在离线情况下工作，允许用户下载您的文档。

配置

内置搜索插件

插件

内置的搜索插件与 Material for MkDocs 无缝集成，使用 lunr 和 lunr-languages 提供多语言的客户端搜索功能。它默认启用，但在使用其他插件时必须重新添加到 mkdocs.yml 中：

plugins:
  - search

支持以下配置选项：

lang

默认值：自动设置 – 此选项允许包含 lunr-languages 提供的特定语言的词干分析器。请注意，Material for MkDocs 将根据站点语言自动设置此选项，但可以进行覆盖，例如支持多种语言：

单一语言

plugins:
  - search:
      lang: en

多种语言

plugins:
  - search:
      lang: # (1)!
        - en
        - de

请注意，包含其他语言的支持会增加大约 20kb（在gzip之前）的总体 JavaScript 负载，并且每种语言还会增加 15-30kb。

lunr-languages 支持以下语言：

ar – 阿拉伯语
da – 丹麦语
de – 德语
du – 荷兰语
en – 英语
es – 西班牙语
fi – 芬兰语
fr – 法语
hi – 印地语
hu – 匈牙利语
hy – 亚美尼亚语
it – 意大利语
ja – 日语
kn - 卡纳达语
ko – 韩语
no – 挪威语
pt – 葡萄牙语
ro – 罗马尼亚语
ru – 俄语
sa – 梵语
sv – 瑞典语
ta – 泰米尔语
te – 泰卢固语
th – 泰语
tr – 土耳其语
vi – 越南语
zh – 中文

Material for MkDocs 会尽力支持不在此列表中的语言，并自动回退到产生最佳结果的词干分析器。

separator

默认值：自动设置 – 可以自定义索引和查询分词的分隔符，使得可以索引由空格和-之外的其他字符分隔的词的部分，例如包含.：

plugins:
  - search:
      separator: '[\s\-\.]+'

自从 9.0.0 以来，我们提供了一种更快、更灵活的分词器方法，允许使用前瞻分词进行分词，从而对文档的索引方式产生更大的影响。因此，我们为本站点的搜索使用了以下分隔符设置：

plugins:
  - search:
    separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

将其分解为各个部分，分隔符会产生以下行为：

特殊字符

[\s\-,:!=\[\]()"/]+

表达式的第一部分在每个文档的每个特殊字符之前和之后插入标记边界，包括空格、连字符、逗号、括号和其他特殊字符。如果多个特殊字符相邻，则将它们视为一个。

大小写变化

(?!\b)(?=[A-Z][a-z])

许多编程语言具有PascalCase或camelCase之类的命名约定。通过将此子表达式添加到分隔符中，可以在大小写更改处分割单词，将单词PascalCase分词为Pascal和Case。

[在分词大小写更改方面阅读更多内容][tokenize case changes]

版本字符串

\.(?!\d)

当将.添加到分隔符时，版本字符串（例如1.2.3）将被分割为1、2和3，这将使它们无法通过搜索发现。使用此子表达式时，将引入一个小的前瞻，将保留版本字符串并使其可发现。

[在分词版本号方面阅读更多内容][tokenize version numbers]

HTML/XML 标签

&[lg]t;

如果您的文档包含 HTML/XML 代码示例，您可能希望允许用户查找特定的标签名称。不幸的是，在代码块中，<和>控制字符被编码为<和>。将此子表达式添加到分隔符中即可实现这一点。

[在分词 HTML/XML 标签方面阅读更多内容][tokenize html-xml tags]

中文语言支持

实验性

为了将中文语言支持添加到内置搜索插件中，通过pip安装文本分词库jieba，插件将通过分词器处理所有文本：

pip install jieba

可用的配置选项如下：

jieba_dict

默认值：无 – 此选项允许指定由jieba用于分词文本的自定义词典，替换默认词典：

plugins:
  - search:
      jieba_dict: dict.txt # (1)!

1. [jieba]提供了以下备用词典：

    - [dict.txt.small] – 占用内存较小的词典文件
    - [dict.txt.big] – 支持繁体分词更好的词典文件

jieba_dict_user

默认值：无 – 此选项允许指定一个额外的用户词典，由jieba用于分词文本，增强默认词典：

plugins:
  - search:
      jieba_dict_user: user_dict.txt

用户词典可用于调整分词器以保留技术术语。

搜索建议

功能标志 | 实验性

启用搜索建议后，搜索将显示最可能的最后一个单词的完成方式，用户可以使用++箭头右键++接受它。在mkdocs.yml中添加以下行：

theme:
  features:
    - search.suggest

搜索 search su将提供^{^搜索建议}^作为建议。

搜索结果高亮

功能标志 | 实验性

启用搜索结果高亮后，当用户点击搜索结果时，Material for MkDocs 将在跟随链接后，高亮显示所有出现的结果。在mkdocs.yml中添加以下行：

theme:
  features:
    - search.highlight

搜索 code blocks将高亮显示两个术语的所有出现。

搜索共享

功能标志

当激活搜索共享时，将在重置按钮旁边呈现一个共享按钮，允许深入链接到当前的搜索查询和结果。在mkdocs.yml中添加以下行：

theme:
  features:
    - search.share

当用户点击共享按钮时，URL 将自动复制到剪贴板。

用法

搜索加权

加权支持

可以使用前置属性search.boost将页面在搜索中加权，使其排名更高。在 Markdown 文件的顶部添加以下行：

提升排名

---
search:
  boost: 2 # (1)!
---
# 文档标题

在提升页面时，请温和并从低值开始。

降低排名

---
search:
  boost: 0.5
---
# 文档标题

搜索排除

实验性

可以使用前置属性search.exclude将页面从搜索中排除，从索引中删除它们。在 Markdown 文件的顶部添加以下行：

---
search:
  exclude: true
---
# 文档标题

排除章节

当启用属性列表时，可以通过在 Markdown 标题后添加data-search-exclude指示来从搜索中排除页面的特定章节：

docs/page.md

# 文档标题

## 章节 1

此章节的内容被包含

## 章节 2 { data-search-exclude }

此章节的内容被排除

search_index.json

{
  ...
  "docs": [
    {
      "location":"page/",
      "text":"",
      "title":"文档标题"
    },
    {
      "location":"page/#section-1",
      "text":"<p>此章节的内容被包含</p>",
      "title":"章节 1"
    }
  ]
}

排除块

当启用属性列表时，可以通过在 Markdown 内联或块级元素后添加data-search-exclude指示来从搜索中排除页面的特定章节：

docs/page.md

# 文档标题

包含此块的内容

排除此块的内容
{ data-search-exclude }

search_index.json

{
  ...
  "docs": [
    {
      "location":"page/",
      "text":"<p>包含此块的内容</p>",
      "title":"文档标题"
    }
  ]
}