Skip to content

从搜索中排除内容

¥Excluding content from search

最新的 Insiders 版本带来了三种新的简单方法，可以从搜索索引中排除文档的专用部分，从而实现更细粒度的控制。

¥The latest Insiders release brings three new simple ways to exclude dedicated parts of a document from the search index, allowing for more fine-grained control.

两周前，Material for MkDocs Insiders 发布了一款全新的搜索插件，不仅大幅提升了易用性，还优化了搜索索引的速度和大小。有趣的是，正如上一篇博客文章中所讨论的，我们只是触及了现有功能的冰山一角。此版本带来了一些实用功能，提升了写作体验，允许更精细地控制 Markdown 文件中哪些页面、章节和区块应该被内置搜索功能索引。

¥Two weeks ago, Material for MkDocs Insiders shipped a brand new search plugin, yielding massive improvements in usability, but also in speed and size of the search index. Interestingly, as discussed in the previous blog article, we only scratched the surface of what's now possible. This release brings some useful features that enhance the writing experience, allowing for more fine-grained control of what pages, sections and blocks of a Markdown file should be indexed by the built-in search functionality.

以下部分讨论了从搜索索引中排除页面和版块的现有解决方案。如果您想立即了解新增功能，请跳至下一节。

¥The following section discusses existing solutions for excluding pages and sections from the search index. If you immediately want to learn what's new, skip to the section just after that.

现有技术

¥Prior art

MkDocs 拥有丰富且蓬勃发展的插件生态系统，因此， @chrieke已经开发了一款出色的插件，可以排除 Markdown 文件的特定部分——mkdocs-exclude-search插件。它可以通过以下方式安装：

¥MkDocs has a rich and thriving ecosystem of plugins, and it comes as no surprise that there's already a fantastic plugin by @chrieke to exclude specific sections of a Markdown file – the mkdocs-exclude-search plugin. It can be installed with:

pip install mkdocs-exclude-search

工作原理：该插件对内置搜索插件生成的search_index.json文件进行后处理，使作者能够通过向mkdocs.yml添加几行配置来排除某些页面和部分。例如：

¥How it works: the plugin post-processes the search_index.json file that is generated by the built-in search plugin, giving the author the ability to exclude certain pages and sections by adding a few lines of configuration to mkdocs.yml. An example:

plugins:
  - search
  - exclude-search:
      exclude:
        - page.md
        - page.md#section
        - directory/*
        - /*/page.md

显而易见，该插件遵循以配置为中心的方法，增加了对高级过滤技术的支持，例如使用通配符进行中缀和后缀过滤。虽然这是一个非常强大的想法，但它也有一些缺点：

¥It's easy to see that the plugin follows a configuration-centric approach, which adds support for advanced filtering techniques like infix- and suffix-filtering using wildcards. While this is a very powerful idea, it comes with some downsides:

  1. 排除模式和内容不在同一位置：排除模式需要在mkdocs.yml中定义，而不是作为要排除的相应文档或部分的一部分。这可能会导致排除模式过时，从而引发意外行为：当标题更改时，其 slug（永久链接）也会更改，这可能会突然与模式匹配（或不匹配），例如，当作者修复标题中的拼写错误时。由于排除模式支持使用通配符，不同的作者可能会覆盖彼此的模式而没有任何即时反馈，因为插件只会报告排除的文档数量，而不是排除了哪些文档。1

  2. 排除控制可能过于粗略： mkdocs-exclude-search插件仅允许排除页面和章节。无法排除章节的某些部分，例如，与搜索无关但必须包含在文档中的内容。

什么是新的？

¥What's new?

最新的 Insiders 版本提供了更细粒度的控制功能，用于从搜索索引中排除页面、章节和区块，这些功能通过前置内容以及属性列表实现。请注意，它并非替代mkdocs-exclude-search插件，而是对其进行补充。

¥Exclusion patterns and content are not co-located: exclusion patterns need to be defined in mkdocs.yml, and not as part of the respective document or section to be excluded. This might result in stale exclusion patterns, leading to unintended behavior:

排除页面

¥Excluding pages

通过在相应 Markdown 文件的 front matter 中添加一个简单的指令，即可将整个页面排除在搜索索引之外。好处是，作者现在只需检查文档顶部即可了解该页面是否被排除：

¥When a headline is changed, its slug (permalink) also changes, which might suddenly match (or unmatch) a pattern, e.g., when an author fixes a typo in a headline.

---
search:
  exclude: true
---

# Page title
...

排除部分

¥Excluding sections

如果要排除某个部分，作者可以使用属性列表扩展在标题末尾添加一个名为data-search-exclude的指令。该指令不会包含在最终的 HTML 中，因为搜索指令在页面渲染之前会被搜索插件过滤掉：

¥As exclusion patterns support the use of wildcards, different authors might overwrite each other's patterns without any immediate feedback since the plugin does only report the number of excluded documents – not what has been excluded.1

# 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

如果需要更细粒度的控制，可以将该指令添加到属性列表扩展正式支持的任何块级元素或内联级元素中：

¥Exclusion control might be too coarse: The mkdocs-exclude-search plugin only allows for the exclusion of pages and sections. It's not possible to exclude parts of a section, e.g., content that is irrelevant to search but must be included as part of the documentation.

# 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"
    },
  ]
}

结论

¥Conclusion

最新版本提供了三种简单的方法，可以更精确地控制哪些内容进入搜索索引，哪些内容不进入。它补充了功能强大的mkdocs-exclude-search插件，允许使用新方法来调整搜索索引的结构、大小和内容。

¥The latest Insiders release brings fine-grained control for excluding pages, sections, and blocks from the search index, implemented through front matter, as well as the Attribute Lists. Note that it doesn't replace the mkdocs-exclude-search plugin but complements it.

  1. 当日志级别设置为DEBUG时，插件将准确报告哪些页面和部分已从搜索索引中排除，但 MkDocs 现在将用来自其核心和其他插件的调试输出淹没终端。↩