Skip to content

设置站点搜索

¥Setting up site search

Material for MkDocs 提供了出色的客户端搜索功能，无需集成可能不符合隐私法规的第三方服务。此外，搜索功能甚至可以离线运行，允许用户下载您的文档。

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

配置

¥Configuration

内置搜索插件

¥Built-in search plugin

0.1.0

¥0.1.0

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

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

plugins:
  - search

有关所有设置的列表，请参阅插件文档。

¥For a list of all settings, please consult the plugin documentation.

搜索建议

¥Search suggestions

7.2.0

¥7.2.0

启用搜索建议后，搜索将显示最后一个单词最可能的补全，您可以使用右键接受。将以下几行添加到mkdocs.yml中：

¥When search suggestions are enabled, the search will display the likeliest completion for the last word which can be accepted with the Right key. Add the following lines to mkdocs.yml:

theme:
  features:
    - search.suggest

搜索search su会产生搜索建议。

¥Searching for search su yields search suggestions as a suggestion.

搜索突出显示

¥Search highlighting

7.2.0

¥7.2.0

启用搜索高亮显示后，当用户点击搜索结果时，Material for MkDocs 会在点击链接后高亮显示所有匹配结果。将以下几行添加到mkdocs.yml中：

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

theme:
  features:
    - search.highlight

搜索代码块会突出显示这两个术语的所有出现情况。

¥Searching for code blocks highlights all occurrences of both terms.

搜索共享

¥Search sharing

7.2.0

¥7.2.0

当搜索共享功能激活时，分享按钮显示在重置按钮旁边，以便深度链接到当前的搜索查询和结果。将以下几行添加到mkdocs.yml中：

¥When search sharing is activated, a 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:

theme:
  features:
    - search.share

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

¥When a user clicks the share button, the URL is automatically copied to the clipboard.

用法

¥Usage

搜索提升

¥Search boosting

8.3.0

¥8.3.0

可以使用前置的search.boost属性来提升页面的搜索排名，从而提高页面的排名。在 Markdown 文件的顶部添加以下几行：

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

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

# Page title
...

  1. 提升页面时，请保持温和并从较低的值开始。

---
search:
  boost: 0.5
---

# Page title
...

搜索排除

¥Search exclusion

9.0.0

¥9.0.0

可以使用前置的search.exclude属性将页面排除在搜索范围之外，从而将其从索引中移除。在 Markdown 文件的顶部添加以下几行：

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

---
search:
  exclude: true
---

# Page title
...

排除部分

¥Excluding sections

启用属性列表后，可以通过在 Markdown 标题后添加data-search-exclude指令来将页面的特定部分排除在搜索之外：

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

# Page title

## Section 1

The content of this section is included

## Section 2 { data-search-exclude }

The content of this section is excluded

{
  ...
  "docs": [
    {
      "location":"page/",
      "text":"",
      "title":"Document title"
    },
    {
      "location":"page/#section-1",
      "text":"<p>The content of this section is included</p>",
      "title":"Section 1"
    }
  ]
}

排除区块

¥Excluding blocks

启用属性列表后，可以通过在 Markdown 内联或块级元素后添加data-search-exclude指令来将页面的特定部分排除在搜索之外：

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

# Page title

The content of this block is included

The content of this block is excluded
{ data-search-exclude }

{
  ...
  "docs": [
    {
      "location":"page/",
      "text":"<p>The content of this block is included</p>",
      "title":"Document title"
    }
  ]
}