内置搜索插件¶

搜索插件在标题中添加了一个搜索栏，允许用户搜索您的 文档。它由lunr.js提供支持，这是一个轻量级的全文搜索引擎 对于浏览器来说，消除了对外部服务的需求，甚至可以工作 在构建[支持离线的文档]时。

客观的¶

工作原理¶

该插件扫描生成的HTML，并从所有页面构建搜索索引 通过提取章节标题和内容。它保留了一些内联 格式类似于代码块和列表，但会删除所有其他格式，因此 搜索索引尽可能小。

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

何时使用¶

通常建议使用插件作为交互式搜索功能 是每一份好文件的重要组成部分。此外，该插件还集成了 与MkDocs的其他几个[内置插件]完美配合 提供：

配置¶

与所有[内置插件]一样，开始使用搜索插件是 直截了当。只需将以下行添加到mkdocs.yml和您的用户 将能够搜索您的文档：

plugins:
  - search

搜索插件内置于MkDocs的Material中，不需要 安装。

一般的¶

以下设置可用：

¶

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

plugins:
  - search:
      enabled: false

搜索¶

以下设置可供搜索：

¶

使用此设置指定搜索索引的语言，启用[词干] 支持英语以外的其他语言。默认值为自动 根据[站点语言]计算，但可以显式设置为另一种语言 甚至支持多种语言，包括：

plugins:
  - search:
      lang: en

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

语言支持由lunr languages提供，这是一个 由lunr.js维护的特定于语言的词干分析器和停用词 开源社区。

lunr languages目前支持以下语言：

如果lunr languages不支持所选的[站点语言]， 该插件退回到另一种能产生最佳词干结果的语言。 如果你发现搜索结果不令人满意，你可以做出贡献 通过添加对您的语言的支持，将其添加到lunr languages。

¶

使用此设置指定构建时用于拆分单词的分隔符 客户端的搜索索引。默认值是自动计算的 来自site language，但也可以通过以下方式显式设置为另一个值：

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

分隔符支持[正向和反向前瞻断言]，这允许 用于精确控制单词表达方式的相当复杂的表达式 在构建搜索索引时进行拆分。

该分离器被分解为多个部分，从而引发以下行为：

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

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

\.(?!\d)

&[lg]t;

¶

使用此设置指定用于过滤和 使用[`separate][config.separate]对令牌进行标记后展开令牌，以及 在将它们添加到搜索索引之前。默认值为自动 根据site language计算，但也可以显式设置为：

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

可以使用以下管道功能：

• stemmer – 茎标记到其根形式, e.g. running to run
• stopWordFilter – 根据以下条件过滤常用词, e.g. a, the, etc.
• trimmer – 修剪标记中的空格

市场细分¶

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

以下设置可用于分段：

¶

使用此设置指定jieba使用的[自定义词典] 分割文本，替换默认词典。jieba来了 几本词典，可以与以下词典一起使用：

plugins:
  - search:
      jieba_dict: dict.txt

以下词典由jieba提供：

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

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

¶

使用此设置指定要使用的其他用户词典用于分割文本，扩充默认词典。用户 字典是调整分段器的理想选择：

plugins:
  - search:
      jieba_dict_user: user_dict.txt

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

使用¶

元数据¶

以下属性可用：

¶

使用此属性可增加或减少搜索中页面的相关性 结果，给他们更多的权重。使用高于“1”的值进行排名 低于“1”进行排名：

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

# Page title
...

---
search:
  boost: 0.5
---

# Page title
...

¶

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

---
search:
  exclude: true
---

# Page title
...