内置搜索插件¶

搜索插件在头部添加了一个搜索栏，允许用户搜索您的文档。它由 lunr.js 提供支持，这是一款轻量级的浏览器全文搜索引擎，消除了对外部服务的需求，并且在构建 离线可用文档 时也能正常工作。

目标¶

工作原理¶

该插件扫描生成的 HTML，并通过提取部分标题和内容来构建所有页面和部分的搜索索引。它保留了一些内联格式，如代码块和列表，但移除了所有其他格式，以使搜索索引尽可能小。

当用户访问您的网站时，搜索索引被发送到浏览器，使用 lunr.js 进行索引，并可以快速简单地查询——无需服务器。这确保了搜索索引始终与您的文档保持最新，从而产生准确的结果。

何时使用¶

通常建议使用该插件，因为交互式搜索功能是每个优秀文档的重要组成部分。此外，该插件与 Material for MkDocs 提供的其他多个 内置插件 完美集成：

配置¶

9.0.0 search – built-in

与所有 内置插件 一样，开始使用搜索插件非常简单。只需将以下行添加到 mkdocs.yml 中，您的用户就可以搜索您的文档：

plugins:
  - search

搜索插件内置于 Material for MkDocs 中，无需安装。

一般设置¶

以下设置可用：

enabled¶

9.3.2 true

使用此设置在 构建项目 时启用或禁用插件。通常不需要指定此设置，但如果您想禁用插件，请使用：

plugins:
  - search:
      enabled: false

搜索¶

以下设置可用于搜索：

lang¶

9.0.0

使用此设置指定搜索索引的语言，启用对英语以外其他语言的 词干提取 支持。默认值是从 网站语言 自动计算的，但可以显式设置为其他语言，甚至多种语言：

plugins:
  - search:
      lang: en

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

语言支持由 lunr 语言 提供，这是一个由开源社区维护的语言特定词干提取器和停用词的集合。

当前 lunr 语言 支持以下语言：

如果 lunr 语言 不支持所选的 网站语言，插件将回退到其他语言，以获得最佳的词干提取结果。如果您发现搜索结果不令人满意，可以通过为您的语言添加支持来为 lunr 语言 贡献。

separator¶

9.0.0

使用此设置指定在客户端构建搜索索引时用于拆分单词的分隔符。默认值是从 网站语言 自动计算的，但也可以显式设置为其他值：

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

分隔符支持 正向和负向前瞻断言，这允许使用相当复杂的表达式，从而精确控制在构建搜索索引时如何拆分单词。

分隔符的各个部分产生以下行为：

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

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

\.(?!\d)

&[lg]t;

pipeline¶

9.0.0

使用此设置指定在使用 separator 对令牌进行标记化后以及在将它们添加到搜索索引之前，用于过滤和扩展令牌的 管道函数。默认值是从 网站语言 自动计算的，但也可以显式设置为：

plugins:
  - search:
      pipeline:
        - stemmer
        - stopWordFilter
        - trimmer

可以使用以下管道函数：

• stemmer – 将令牌词干化为其根形式，例如将 running 变为 run
• stopWordFilter – 根据常见词过滤，例如 a、the 等
• trimmer – 修剪令牌中的空格

分词¶

该插件通过 jieba 支持中文的文本分词，这是一个流行的中文文本分词库。其他语言如日语和韩语目前在客户端进行分词，但我们考虑在未来将此功能移入插件中。

以下设置可用于分词：

jieba_dict¶

9.2.0

使用此设置指定 jieba 用于分词的 自定义词典，以替换默认词典。jieba 附带多个词典，可以使用：

plugins:
  - search:
      jieba_dict: dict.txt

jieba 提供以下词典：

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

提供的路径是从根目录解析的。

jieba_dict_user¶

9.2.0

使用此设置指定一个额外的 用户词典，供 jieba 用于分词，增强默认词典。用户词典非常适合调优分词器：

plugins:
  - search:
      jieba_dict_user: user_dict.txt

提供的路径是从根目录解析的。

用法¶

元数据¶

以下属性可用：

boost¶

8.3.0

使用此属性增加或减少页面在搜索结果中的相关性，给予其更高的权重。使用大于 1 的值提高排名，使用小于 1 的值降低排名：

---
search:
  boost: 2 # (1)!
---

# 页面标题
...

---
search:
  boost: 0.5
---

# 页面标题
...

exclude¶

9.0.0

使用此属性将页面从搜索结果中排除。请注意，这不仅会移除该页面，还会将该页面的所有子部分也从搜索结果中移除：

---
search:
  exclude: true
---

# 页面标题
...