内置标签插件¶
标签插件为使用标签对页面进行分类提供了一级支持，增加了将相关页面分组的可能性，并使其通过搜索和专用标签索引可被发现。如果您的文档量很大，标签可以帮助更快地发现相关信息。
目标¶
工作原理¶
该插件扫描所有页面的 tags 元数据属性，并生成一个标签索引，这是一个标签及其出现页面的倒排列表。标签索引可以位于 nav 的任何位置，从而在为您的项目添加标签时提供最大的灵活性。
何时使用¶
如果您想为项目添加一个或多个标签索引，标签插件是一个完美的选择，因为它使这个过程变得极其简单。此外，它与 Material for MkDocs 提供的其他几个 内置插件 完美集成：
配置¶
与所有 内置插件 一样，开始使用标签插件也很简单。只需将以下行添加到 mkdocs.yml，并开始使用 tags 来对页面进行分类：
标签插件内置于 Material for MkDocs 中，无需单独安装。
一般设置¶
以下设置可用：
enabled¶
9.1.7 true
使用此设置在 构建项目时 启用或禁用插件。通常不需要指定此设置，但如果您想禁用插件，可以使用：
标签¶
以下设置可用于标签：
tags¶
9.3.2 true
使用此设置启用或禁用标签的渲染。插件仍然会从所有页面提取标签，例如，用于 导出标签 而不渲染它们。可以通过以下方式禁用渲染：
如果启用了 export_only，则此设置会自动禁用。
tags_file¶
使用此设置指定标签索引的位置，该页面用于渲染所有标签及其关联页面的列表。如果指定了此设置，标签将变为可点击，指向标签索引中的相应部分：
持有标签索引的页面可以在 mkdocs.yml 的 nav 部分的任何位置链接。此设置不是必需的 – 仅在您希望拥有标签索引时使用。
提供的路径是从 docs 目录 解析的。
tags_slugify¶
使用此设置更改从帖子标题生成 URL 兼容的 slug 的函数。默认情况下，使用 Python Markdown 扩展 中的 slugify 函数，如下所示：
默认配置是 Unicode 感知的，并且应该为所有语言生成良好的 slug。当然，您也可以提供自定义的 slug 化函数以获得更细粒度的控制。
tags_slugify_separator¶
9.6.0 -
使用此设置更改传递给作为 tags_slugify 一部分的 slug 化函数的分隔符。默认情况下是一个连字符，但可以设置为任何字符串，例如 _：
tags_slugify_format¶
9.6.0 tag:{slug}
使用此设置更改生成标签 slug 时使用的格式字符串。为标签 slug 添加一个使其唯一的前缀是个好主意，默认值为：
可用的占位符如下：
slug– 标签 slug，使用tags_slugify进行 slug 化
tags_hierarchy¶
9.7.0 false
使用此设置启用对标签层次结构（嵌套标签，例如 foo/bar）的支持。如果您打算创建标签的层次列表，可以在 mkdocs.yml 中启用此设置：
tags_hierarchy_separator¶
9.7.0 /
使用此设置更改创建标签层次结构时使用的分隔符。默认情况下，标签由正斜杠 / 分隔，但您可以将其更改为任何字符串，例如 .：
tags_sort_by¶
9.6.0 material.plugins.tags.tag_name
使用此设置指定用于比较标签的自定义函数。默认情况下，标签比较是区分大小写的，但您可以使用 tag_name_casefold 进行不区分大小写的比较：
您还可以定义自己的比较函数，该函数必须返回一个表示标签的字符串或数字，用于排序，并在 tags_sort_by 中引用它。
tags_sort_reverse¶
9.6.0 false
使用此设置反转比较标签时的排序顺序。默认情况下，标签按升序排序，但您可以按如下方式反转排序：
tags_name_property¶
使用此设置更改插件使用的前端属性的名称。通常不需要更改此设置，但如果您想更改它，可以使用：
tags_name_variable¶
9.6.0 tags
使用此设置更改插件使用的模板变量的名称。通常不需要更改此设置，但如果您想更改它，可以使用：
tags_allowed¶
该插件允许检查标签是否符合预定义列表，以捕获拼写错误或确保标签不会被任意添加。使用以下方式指定您希望允许的标签：
如果页面引用了不在此列表中的标签，插件将停止构建。可以通过使用 tags 元数据属性将页面分配给标签。
列表¶
以下设置可用于列表：
listings¶
9.6.0 true
使用此设置启用或禁用列表。通常不需要更改此设置，因为列表完全由内联注释创建，但如果需要，可以通过以下方式禁用它们：
如果启用了 export_only，则此设置会自动禁用。
listings_map¶
使用此设置定义列表配置，然后可以在列表中使用自定义标识符引用它们。共享配置是个好主意，特别是当您有许多标签列表时：
然后，只需引用列表标识符：
请参阅 列表部分 以获取所有可用设置的列表。
listings_sort_by¶
9.6.0 material.plugins.tags.item_title
使用此设置指定用于比较列表项的自定义函数。默认情况下，项按其标题排序，但您可以使用以下配置更改排序标准：
您还可以定义自己的比较函数，该函数必须返回一个表示项的字符串或数字，用于排序，并在 listings_sort_by 中引用它。
listings_sort_reverse¶
9.6.0 false
使用此设置反转比较项时的排序顺序。默认情况下，项按升序排序，但您可以按如下方式反转排序：
listings_tags_sort_by¶
9.6.0 material.plugins.tags.tag_name
使用此设置指定用于比较列表中标签的自定义函数。默认情况下，标签比较是区分大小写的，但您可以使用 tag_name_casefold 进行不区分大小写的比较：
您还可以定义自己的比较函数，该函数必须返回一个表示标签的字符串或数字，用于排序，并在 tags_sort_by 中引用它。
listings_tags_sort_reverse¶
9.6.0 false
使用此设置反转比较标签时的排序顺序。默认情况下，标签按升序排序，但您可以按如下方式反转排序：
listings_directive¶
9.6.0 material/tags
使用此设置更改插件在处理页面时查找的指令名称。如果您希望使用比 material/tags 更短的指令，可以使用：
使用此设置，列表现在必须如下引用：
listings_toc¶
9.7.0 true
使用此设置启用或禁用标签在目录中显示。如果您不希望标签出现在目录中，可以通过以下方式禁用此行为：
影子标签¶
以下设置可用于影子标签：
shadow¶
9.7.0 false
使用此设置指定插件在 构建项目时 是否应在页面和列表中包含影子标签，这可能对部署预览有用：
shadow_on_serve¶
9.7.0 true
使用此设置控制插件在 预览您的网站 时是否应在页面和列表中包含影子标签。如果您不希望在预览时包含它们，可以使用：
shadow_tags¶
该插件允许指定一个预定义的影子标签列表，可以通过使用 shadow 设置来包含和排除。影子标签必须作为列表指定：
shadow_tags_prefix¶
使用此设置指定一个字符串，该字符串作为每个标签的前缀进行检查。如果标签以此字符串开头，则该标签被标记为影子标签。常见做法是使用 _ 作为前缀：
shadow_tags_suffix¶
使用此设置指定一个字符串，该字符串作为每个标签的后缀进行检查。如果标签以此字符串结尾，则该标签被标记为影子标签。一个选项是使用 Internal 作为后缀：
导出¶
以下设置可用于导出：
export¶
9.7.0 true
使用此设置控制插件是否在您的 site 目录 中创建 tags.json 文件，该文件可以被其他插件和项目使用：
export_file¶
9.7.0 tags.json
使用此设置更改导出标签存储的文件路径。通常不需要更改此设置，但如果您需要，可以使用：
提供的路径是从 site 目录 解析的。
export_only¶
9.7.0 false
此设置仅为方便而提供，以通过单个设置禁用标签和列表的渲染（例如，通过使用环境变量），同时保留导出功能：
用法¶
元数据¶
以下属性可用：
tags¶
使用此属性将页面与一个或多个标签关联，使页面出现在生成的标签索引中。标签定义为字符串列表（允许空格）：
如果您希望在将标签分配给页面时防止意外拼写错误，可以通过使用 tags_allowed 设置在 mkdocs.yml 中设置一个预定义的允许标签列表。
列表配置¶
列表配置控制哪些标签包含在列表中或从列表中排除，以及列表是否仅包含当前范围内的页面。此外，列表可以覆盖一些全局配置的值。
以下设置可用：
scope¶
9.6.0 false
此设置指定列表是否仅应考虑在嵌入列表的页面的当前文档子部分中的页面：
shadow¶
此设置指定列表是否应包含影子标签，这允许在每个列表基础上覆盖全局 shadow 设置：
toc¶
此设置指定列表是否应在目录中渲染标签，允许在每个列表基础上覆盖全局 listings_toc 设置：
include¶
使用此设置指定应包含在列表中的标签。每个具有此设置中标签的页面都将在相应标签下列出：
如果此设置为空，则包含所有标签和页面。
exclude¶
使用此设置指定应从列表中排除哪些标签。每个具有此设置中标签的页面都将完全从列表中排除：
如果此设置为空，则不排除任何标签或页面。
限制¶
由于 MkDocs 的架构，标签插件的实现比较棘手。特别是，标签列表标记不能出现在代码块内。有关技术细节，请参见 #8114。