Skip to content

内置搜索插件

¥Built-in search plugin

搜索插件会在页眉处添加一个搜索栏，方便用户搜索您的文档。它由lunr.js提供支持，lunr.js 是一个轻量级的浏览器全文搜索引擎，无需依赖外部服务，甚至在构建离线文档时也能正常工作。

¥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.

客观的

¥Objective

工作原理

¥How it works

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

¥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.

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

¥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

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

¥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:

  • 内置离线插件离线插件增加了对构建离线文档的支持，因此您可以将站点目录作为可下载的.zip文件分发。您的文档无需连接互联网即可运行。

  • 内置元插件元插件可以轻松提升搜索结果中的特定部分，或将其完全排除在索引之外，从而更精细地控制搜索。更轻松地组织和管理不同子部分的搜索

配置

¥Configuration

9.0.0搜索 – 内置

¥   Built-in offline plugin

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

¥The offline plugin adds support for building offline-capable documentation, so you can distribute the site directory as a .zip file that can be downloaded.

plugins:
  - search

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

¥Your documentation can work without connectivity to the internet

一般的

¥General

可用的设置如下：

¥   Built-in meta plugin

enabled

¥enabled

9.3.2正确

¥The meta plugin makes it easy to boost specific sections in search results or to exclude them entirely from being indexed, giving more granular control over search.

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

¥Simpler organization and management of search in different subsections

plugins:
  - search:
      enabled: false

¥Search

以下设置可用于搜索：

¥9.0.0 search – built-in

lang

¥lang

9.0.0

¥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:

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

¥The search plugin is built into Material for MkDocs and doesn't need to be installed.

plugins:
  - search:
      lang: en

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

  1. 请注意，在gzip之前，包含对更多语言的支持会使基本 JavaScript 有效负载增加约 20kb，每种语言再增加 15-30kb。

    ¥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.

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

¥The following settings are available:

lunr languages目前支持以下语言：

¥9.3.2 true

  • ar –阿拉伯语

    ¥ar – Arabic

  • da – 丹麦语

    ¥da – Danish

  • de – 德语

    ¥de – German

  • du – 荷兰语

    ¥du – Dutch

  • en – 英语

    ¥en – English

  • es – 西班牙语

    ¥es – Spanish

  • fi – 芬兰语

    ¥fi – Finnish

  • fr – 法语

    ¥fr – French

  • hi – 印地语

    ¥hi – Hindi

  • hu – 匈牙利语

    ¥hu – Hungarian

  • hy – 亚美尼亚语

    ¥hy – Armenian

  • it – 意大利语

    ¥it – Italian

  • ja – 日语

    ¥ja – Japanese

  • kn卡纳达语

    ¥kn - Kannada

  • ko – 韩语

    ¥ko – Korean

  • no ——挪威语

    ¥no – Norwegian

  • pt – 葡萄牙语

    ¥pt – Portuguese

  • ro – 罗马尼亚语

    ¥ro – Romanian

  • ru – 俄语

    ¥ru – Russian

  • sa – 梵语

    ¥sa – Sanskrit

  • sv – 瑞典语

    ¥sv – Swedish

  • ta – 泰米尔语

    ¥ta – Tamil

  • te – 泰卢固语

    ¥te – Telugu

  • th – 泰语

    ¥th – Thai

  • tr – 土耳其语

    ¥tr – Turkish

  • vi – 越南语

    ¥vi – Vietnamese

  • zh – 中文

    ¥zh – Chinese

如果lunr languages不支持所选的站点语言，插件会回退到其他能够产生最佳词干提取结果的语言。如果您发现搜索结果不令人满意，可以添加对您所选语言的支持，为lunr languages做出贡献。

¥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:

separator

¥separator

9.0.0

¥The following settings are available for search:

使用此设置可指定在客户端构建搜索索引时用于拆分单词的分隔符。默认值是根据站点语言自动计算的，但也可以使用以下命令明确设置为其他值：

¥9.0.0 

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

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

¥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:

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

¥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.

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

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

¥The following languages are currently supported by lunr languages:

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

许多编程语言都有类似PascalCase或camelCase命名约定。通过将此子表达式添加到分隔符，单词会在大小写发生变化时被拆分，从而将单词PascalCase拆分为Pascal和Case 。

¥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.

\.(?!\d)

在分隔符中添加.时，像1.2.3这样的版本字符串会被拆分成1 、 2和3 ，这使得它们无法通过搜索找到。使用此子表达式时，会引入一个小的前瞻操作，以保留版本字符串并使其易于被发现。

¥9.0.0 

&[lg]t;

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

¥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:

pipeline

¥pipeline

9.0.0

¥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:

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

可以使用以下管道函数：

¥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.

  • stemmer – 将词干转换为其根形式，例如running转换为run

    ¥stemmer – Stem tokens to their root form, e.g. running to run

  • stopWordFilter – 根据以下条件过滤常用词，例如a 、 the等。

    ¥stopWordFilter – Filter common words according, e.g. a, the, etc.

  • trimmer ——修剪标记中的空格

    ¥trimmer – Trim whitespace from tokens

分割

¥Segmentation

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

¥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.

以下设置可用于分段：

¥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.

jieba_dict

¥jieba_dict

9.2.0

¥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.

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

¥9.0.0 

plugins:
  - search:
      jieba_dict: dict.txt

jieba提供以下词典：

¥Use this setting to specify the pipeline functions that are used to filter and expand tokens after tokenizing them with the 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:

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

¥The following pipeline functions can be used:

jieba_dict_user

¥jieba_dict_user

9.2.0

¥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.

使用此设置可指定一个额外的用户词典，供Jieba用于分词，从而增强默认词典的功能。用户词典非常适合用于调整分词器：

¥The following settings are available for segmentation:

plugins:
  - search:
      jieba_dict_user: user_dict.txt

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

¥9.2.0

用法

¥Usage

元数据

¥Metadata

可用的属性如下：

¥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:

boost

¥boost

8.3.0

¥The following dictionaries are provided by jieba:

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

¥The provided path is resolved from the root directory.

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

# Page title
...

  1. 提升页面时，始终从较低的值开始。

    ¥When boosting pages, always start with low values.

---
search:
  boost: 0.5
---

# Page title
...

exclude

¥exclude

9.0.0

¥9.2.0

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

¥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:

---
search:
  exclude: true
---

# Page title
...