内置标签插件¶

¥Built-in tags plugin¶

标签插件新增了一流的支持，支持使用标签对页面进行分类，并支持将相关页面分组，以便通过搜索和专用标签索引轻松找到它们。如果您的文档规模庞大，标签可以帮助您更快地找到相关信息。

¥The tags plugin adds first-class support for categorizing pages with the use of tags, adding the possibility to group related pages and make them discoverable via search and dedicated tags indexes. If your documentation is large, tags can help to discover relevant information faster.

客观的¶

¥Objective¶

工作原理¶

¥How it works¶

该插件会扫描所有页面的tags 元数据属性，并生成一个 tags 索引，该索引是一个倒排列表，其中包含标签及其所在页面。tags 索引可以位于nav中的任何位置，从而在向项目添加标签时提供最大的灵活性。

¥The plugin scans all pages for the tags metadata property and generates a tags index, which is an inverted list of tags and the pages they appear on. The tags index can be located anywhere in the nav, allowing for maximum flexibility when adding tags to your project.

何时使用¶

¥When to use it¶

如果您想在项目中添加一个或多个标签索引，那么 tags 插件是一个完美的选择，因为它使这个过程变得非常简单。此外，它与 Material for MkDocs 提供的其他几个内置插件完美集成：

¥If you want to add one or multiple tags indexes to your project, the tags plugin is a perfect choice as it makes this process ridiculously simple. Additionally, it integrates perfectly with several of the other built-in plugins that Material for MkDocs offers:

内置元插件元插件可以确保项目的子部分使用特定标签进行注释，这样在添加页面时就不会忘记它们。更轻松地组织和管理不同子部分中的标签
内置博客插件标签插件允许将文章与项目中的页面一起分类，以提高文章的可发现性，并将文章与文档关联起来。文档的标签系统已与您的博客集成。

配置¶

¥Configuration¶

8.2.0标签 – 内置

¥ Built-in meta plugin

与所有内置插件一样，tags插件的使用也非常简单。只需将以下几行添加到mkdocs.yml ，即可开始使用标签对页面进行分类：

¥The meta plugin makes it possible to ensure that subsections of your project are annotated with specific tags, so they can't be forgotten when adding pages.

plugins:
  - tags

标签插件内置于 Material for MkDocs 中，无需安装。

¥Simpler organization and management of tags in different subsections

一般的¶

¥General¶

可用的设置如下：

¥ Built-in blog plugin

`enabled`¶

¥enabled¶

9.1.7真实

¥The tags plugin allows to categorize posts alongside with pages in your project, to improve their discoverability and connect posts to your documentation.

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

¥Your documentation's tag system integrates with your blog

plugins:
  - tags:
      enabled: false

标签¶

¥Tags¶

标签可进行以下设置：

¥8.2.0 tags – built-in

`tags`¶

¥tags¶

9.3.2正确

¥As with all built-in plugins, getting started with the tags plugin is straightforward. Just add the following lines to mkdocs.yml, and start using tags to categorize your pages:

使用此设置可启用或禁用标签渲染。插件仍会从所有页面中提取标签，例如，导出标签但不渲染它们。可以使用以下方式禁用渲染：

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

plugins:
  - tags:
      tags: false

如果启用了export_only ，则此设置将自动禁用。

¥The following settings are available:

`tags_file`¶

¥tags_file¶

8.2.0

¥9.1.7 true

此设置已弃用

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

从9.6.0版本开始，此设置已弃用，因为此版本对标签插件进行了彻底重写，其功能比上一版本更加强大。现在，标签列表可以在任何页面上使用。

¥The following settings are available for tags:

使用此设置可指定标签索引的位置，该页面用于呈现所有标签及其关联页面的列表。如果指定了此设置，标签将变为可点击状态，并指向标签索引中的相应部分：

¥9.3.2 true

plugins:
  - tags:
      tags_file: tags.md

保存标签索引的页面可以链接到mkdocs.yml的nav部分中的任何位置。此设置不是必需的——仅当您需要标签索引时才需要使用它。

¥Use this setting to enable or disable rendering of tags. The plugin still extracts tags from all pages, e.g., for exporting tags without rendering them. Rendering can be disabled with:

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

¥This setting is automatically disabled if export_only is enabled.

`tags_slugify`¶

¥tags_slugify¶

9.6.0 pymdownx.slugs.slugify

¥8.2.0

使用此设置可更改从文章标题生成 URL 兼容 slug 的函数。默认情况下，使用Python Markdown 扩展中的slugify函数，如下所示：

¥This setting is deprecated

plugins:
  - tags:
      tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

默认配置支持 Unicode，应该能为所有语言生成良好的 slug。当然，您也可以提供自定义 slugification 函数，以实现更精细的控制。

¥As of version 9.6.0, this setting is deprecated, as this version ships a ground up rewrite of the tags plugin which is much more powerful than the previous version. Tags listings can be used on any page now.

`tags_slugify_separator`¶

¥tags_slugify_separator¶

9.6.0-

¥Use this setting to specify the location of the tags index, which is the page used to render a list of all tags and their associated pages. If this setting is specified, tags become clickable, pointing to the corresponding section in the tags index:

使用此设置可以更改传递给tags_slugify函数的分隔符。默认值为连字符，但可以设置为任何字符串，例如_ ：

¥The page holding the tags index can be linked anywhere in the nav section of mkdocs.yml. This setting is not required – you should only use it if you want to have a tags index.

plugins:
  - tags:
      tags_slugify_separator: _

`tags_slugify_format`¶

¥tags_slugify_format¶

9.6.0标签：{slug}

¥The provided path is resolved from the docs directory.

使用此设置可更改生成标签 slug 时使用的格式字符串。建议在标签 slug 前添加一个字符串以使其唯一，默认值为：

¥9.6.0 pymdownx.slugs.slugify

plugins:
  - tags:
      tags_slugify_format: "tag:{slug}"

可用的占位符如下：

¥Use this setting to change the function for generating URL-compatible slugs from post titles. By default, the slugify function from Python Markdown Extensions is used as follows:

slug – 标签 slug，使用tags_slugify进行 slugify
¥slug – Tag slug, slugified with tags_slugify

`tags_hierarchy`¶

¥tags_hierarchy¶

insiders-4.48.0 false

¥The default configuration is Unicode-aware and should produce good slugs for all languages. Of course, you can also provide a custom slugification function for more granular control.

使用此设置可启用对标签层次结构（嵌套标签，例如foo/bar ）的支持。如果您打算创建标签的层次结构列表，可以在mkdocs.yml中启用此设置，如下所示：

¥9.6.0 -

plugins:
  - tags:
      tags_hierarchy: true

`tags_hierarchy_separator`¶

¥tags_hierarchy_separator¶

内部人员-4.48.0 /

¥Use this setting to change the separator that is passed to the slugification function set as part of tags_slugify. While the default is a hyphen, it can be set to any string, e.g., _:

使用此设置可更改创建标签层次结构时使用的分隔符。默认情况下，标签以正斜杠/分隔，但您可以将其更改为任何字符串，例如. ：

¥9.6.0 tag:{slug}

plugins:
  - tags:
      tags_hierarchy_separator: .

`tags_sort_by`¶

¥tags_sort_by¶

9.6.0材质.插件.标签.标签名称

¥Use this setting to change the format string that is used when generating tag slugs. It is a good idea to prefix tag slugs with a string that makes them unique, the default being:

使用此设置指定用于比较标签的自定义函数。默认情况下，标签比较区分大小写，但您可以使用tag_name_casefold进行不区分大小写的比较：

¥The following placeholders are available:

plugins:
  - tags:
      tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold

您还可以定义自己的比较函数，该函数必须返回代表标签的字符串或数字，用于排序，并在tags_sort_by中引用它。

¥ insiders-4.48.0 false

`tags_sort_reverse`¶

¥tags_sort_reverse¶

9.6.0错误

¥Use this setting to enable support for tag hierarchies (nested tags, e.g., foo/bar). If you intend to create hierarchical listings of tags, you can enable this setting in mkdocs.yml with:

使用此设置可在比较标签时反转其排序顺序。默认情况下，标签按升序排列，但您可以按如下方式反转排序：

¥ insiders-4.48.0 /

plugins:
  - tags:
      tags_sort_reverse: true

`tags_name_property`¶

¥tags_name_property¶

9.6.0标签

¥Use this setting to change the separator that is used when creating tag hierarchies. By default, tags are separated by a forward slash /, but you can change this to any string, e.g., .:

使用此设置可以更改插件使用的前置属性的名称。通常不需要更改此设置，但如果您想更改它，可以使用：

¥9.6.0 material.plugins.tags.tag_name

plugins:
  - tags:
      tags_name_property: tags

`tags_name_variable`¶

¥tags_name_variable¶

9.6.0标签

¥Use this setting to specify a custom function for comparing tags. By default, tag comparison is case-sensitive, but you can use tag_name_casefold for case-insensitive comparison:

使用此设置可以更改插件使用的模板变量的名称。通常不需要更改此设置，但如果您想更改它，可以使用：

¥You can also define your own comparison function, which must return a string or number representing the tag, that is used for sorting, and reference it in tags_sort_by.

plugins:
  - tags:
      tags_name_variable: tags

`tags_allowed`¶

¥tags_allowed¶

9.6.0

¥9.6.0 false

该插件允许根据预定义列表检查标签，以便发现拼写错误或确保标签不会被随意添加。请使用以下命令指定要允许的标签：

¥Use this setting to reverse the order in which tags are sorted when comparing them. By default, tags are sorted in ascending order, but you can reverse ordering as follows:

plugins:
  - tags:
      tags_allowed:
        - HTML5
        - JavaScript
        - CSS

如果页面引用了不在此列表中的标签，插件将停止构建。您可以使用tags元数据属性将页面分配给标签。

¥9.6.0 tags

房源¶

¥Listings¶

列表有以下设置可用：

¥Use this setting to change the name of the front matter property that is used by the plugin. It is normally not necessary to change this setting, but if you want to change it, you can use:

`listings`¶

¥listings¶

9.6.0真实

¥9.6.0 tags

使用此设置可启用或禁用列表。通常无需更改此设置，因为列表完全由内联评论创建，但如有必要，您可以使用以下方法禁用它们：

¥Use this setting to change the name of the template variable that is used by the plugin. It is normally not necessary to change this setting, but if you want to change it, you can use:

plugins:
  - tags:
      listings: false

如果启用了export_only ，则此设置将自动禁用。

¥9.6.0

`listings_map`¶

¥listings_map¶

9.6.0

¥The plugin allows to check tags against a predefined list, in order to catch typos or make sure that tags are not arbitrarily added. Specify the tags you want to allow with:

使用这个定义列表配置，然后您可以在带有自定义标识符的列表中引用这些配置。共享配置是个好主意，尤其是在您拥有多个标签列表时：

¥The plugin stops the build if a page references a tag that is not part of this list. Pages can be assigned to tags by using the tags metadata property.

plugins:
  - tags:
      listings_map:
        custom-id:
          scope: true
          exclude: Internal

然后，只需引用列表标识符：

¥The following settings are available for listings:

<!-- material/tags custom-id -->

请参阅列表部分以获取所有可用设置的列表。

¥9.6.0 true

`listings_sort_by`¶

¥listings_sort_by¶

9.6.0材质.插件.标签.item_title

¥Use this setting to enable or disable listings. It is normally not necessary to change this setting, as listings are created entirely by inline comments, but you can disable them if necessary with:

使用此设置指定用于比较列表项的自定义函数。默认情况下，项目按标题排序，但您可以使用以下配置更改排序标准：

¥This setting is automatically disabled if export_only is enabled.

Sort by item titleSort by item URL

plugins:
  - tags:
      listings_sort_by: !!python/name:material.plugins.tags.item_title

plugins:
  - tags:
      listings_sort_by: !!python/name:material.plugins.tags.item_url

您还可以定义自己的比较函数，该函数必须返回代表项目的字符串或数字，用于排序，并在listings_sort_by中引用它。

¥9.6.0

`listings_sort_reverse`¶

¥listings_sort_reverse¶

9.6.0错误

¥Use this define listing configurations that you can then reference in listings with a custom identifier. Sharing configurations is a good idea, especially when you have many tag listings:

使用此设置可在比较项目时反转项目的排序顺序。默认情况下，项目按升序排列，但您可以按如下方式反转排序：

¥Then, just reference the listing identifier:

plugins:
  - tags:
      listings_sort_reverse: true

`listings_tags_sort_by`¶

¥listings_tags_sort_by¶

9.6.0材质.插件.标签.标签名称

¥See the listings section for a list of all available settings.

使用此设置指定用于比较列表中标签的自定义函数。默认情况下，标签比较区分大小写，但您可以使用tag_name_casefold来实现不区分大小写：

¥9.6.0 material.plugins.tags.item_title

plugins:
  - tags:
      tags_sort_by: !!python/name:material.plugins.tags.tag_name_casefold

您还可以定义自己的比较函数，该函数必须返回代表标签的字符串或数字，用于排序，并在tags_sort_by中引用它。

¥Use this setting to specify a custom function for comparing listing items. By default, items are ordered by their titles, but you can change the sorting criterion with the following configuration:

`listings_tags_sort_reverse`¶

¥listings_tags_sort_reverse¶

9.6.0错误

¥You can also define your own comparison function, which must return a string or number representing the item, that is used for sorting, and reference it in listings_sort_by.

使用此设置可在比较标签时反转其排序顺序。默认情况下，标签按升序排列，但您可以按如下方式反转排序：

¥9.6.0 false

plugins:
  - tags:
      tags_sort_reverse: true

`listings_directive`¶

¥listings_directive¶

9.6.0材料/标签

¥Use this setting to reverse the order in which items are sorted when comparing them. By default, items are sorted in ascending order, but you can reverse ordering as follows:

使用此设置可更改插件在处理页面时查找的指令名称。如果您想使用比material/tags更短的指令，可以使用：

¥9.6.0 material.plugins.tags.tag_name

plugins:
  - tags:
      listings_directive: $tags

使用此设置，列表现在必须按如下方式引用：

¥Use this setting to specify a custom function for comparing tags in listings. By default, tag comparison is case-sensitive, but you can use tag_name_casefold for case-insensitivity:

<!-- $tags { include: [foo, bar] } -->

`listings_toc`¶

¥listings_toc¶

insiders-4.48.0真实

¥You can also define your own comparison function, which must return a string or number representing the tag, that is used for sorting, and reference it in tags_sort_by.

使用此设置可以启用或禁用目录中显示的标签。如果您不希望标签显示在目录中，可以使用以下命令禁用此行为：

¥9.6.0 false

plugins:
  - tags:
      listings_toc: false

影子标签¶

¥Shadow tags¶

阴影标签有以下设置可用：

¥Use this setting to reverse the order in which tags are sorted when comparing them. By default, tags are sorted in ascending order, but you can reverse ordering as follows:

`shadow`¶

¥shadow¶

insiders-4.48.0 false

¥9.6.0 material/tags

使用此设置可以指定插件在构建项目时是否应在页面和列表中包含阴影标签，这可能对部署预览有用：

¥Use this setting to change the name of the directive the plugin will look for when processing pages. If you want to use a shorter directive than material/tags, you could use:

Show shadow tagsHide shadow tags

plugins:
  - tags:
      shadow: true

plugins:
  - tags:
      shadow: false

`shadow_on_serve`¶

¥shadow_on_serve¶

insiders-4.48.0真实

¥Using this setting, listings must now be referenced as such:

使用此设置可控制插件在预览网站时是否在页面和列表中包含阴影标签。如果您不想在预览时包含它们，请使用：

¥ insiders-4.48.0 true

plugins:
  - tags:
      shadow_on_serve: false

`shadow_tags`¶

¥shadow_tags¶

insiders-4.48.0

¥Use this setting to enable or disable tags showing up in the table of contents. If you don't want tags to show up in the table of contents, you can disable this behavior with:

该插件允许指定一个预定义的影子标签列表，这些标签可以通过使用shadow设置在构建中包含或排除。影子标签必须以列表形式指定：

¥The following settings are available for shadow tags:

plugins:
  - tags:
      shadow_tags:
        - Draft
        - Internal

`shadow_tags_prefix`¶

¥shadow_tags_prefix¶

insiders-4.48.0

¥ insiders-4.48.0 false

使用此设置可指定一个字符串，该字符串将作为每个标签的前缀进行检查。如果标签以此字符串开头，则该标签将被标记为影子标签。常见的做法是使用_作为前缀：

¥Use this setting to specify whether the plugin should include shadow tags on pages and in listings when building your project, which might be useful for deploy previews:

plugins:
  - tags:
      shadow_tags_prefix: _

`shadow_tags_suffix`¶

¥shadow_tags_suffix¶

insiders-4.48.0

¥ insiders-4.48.0 true

使用此设置可指定一个字符串，用于检查每个标签的后缀。如果标签以此字符串结尾，则该标签会被标记为影子标签。一个选项是使用Internal作为后缀：

¥Use this setting to control whether the plugin should include shadow tags on pages and in listings when previewing your site. If you don't wish to include them when previewing, use:

plugins:
  - tags:
      shadow_tags_suffix: Internal

出口¶

¥Export¶

导出时可以使用以下设置：

¥ insiders-4.48.0

`export`¶

¥export¶

insiders-4.49.0真实

¥The plugin allows to specify a predefined list of shadow tags which can be included and excluded from builds by using the shadow setting. Shadow tags must be specified as a list:

使用此设置来控制插件是否在您的站点目录中创建tags.json文件，然后其他插件和项目可以使用该文件：

¥ insiders-4.48.0

plugins:
  - tags:
      export: true

`export_file`¶

¥export_file¶

insiders-4.49.0标签.json

¥Use this setting to specify a string that is checked as a prefix for each tag. If the tag starts with this string, the tag is marked as a shadow tag. A common practice is to use _ as a prefix:

使用此设置可更改存储导出标签的文件的路径。通常无需更改此设置，但如果需要，请使用：

¥ insiders-4.48.0

plugins:
  - tags:
      export_file: tags.json

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

¥Use this setting to specify a string that is checked as a suffix for each tag. If the tag ends with this string, the tag is marked as a shadow tag. One option can be to use Internal as a suffix:

`export_only`¶

¥export_only¶

insiders-4.49.0 false

¥The following settings are available for exporting:

提供此设置仅仅是为了方便使用单一设置（例如通过使用环境变量）禁用标签和列表的渲染，同时保持导出功能：

¥ insiders-4.49.0 true

plugins:
  - tags:
      export_only: true

这将自动禁用标签和列表设置。

¥Use this setting to control whether the plugin creates a tags.json file inside your site directory, which can then be consumed by other plugins and projects:

用法¶

¥Usage¶

元数据¶

¥Metadata¶

可用的属性如下：

¥ insiders-4.49.0 tags.json

`tags`¶

¥tags¶

8.2.0

¥Use this setting to change the path of the file where the exported tags are stored. It's normally not necessary to change this setting, but if you need to, use:

使用此属性可将页面与一个或多个标签关联，从而使该页面显示在生成的标签索引中。标签定义为字符串列表（允许使用空格）：

¥The provided path is resolved from the site directory.

---
tags:
  - HTML5
  - JavaScript
  - CSS
---

# Page title
...

如果您想防止在为页面分配标签时出现意外的拼写错误，您可以使用tags_allowed设置在mkdocs.yml中设置预定义的允许标签列表。

¥ insiders-4.49.0 false

列表配置¶

¥Listing configuration¶

列表配置控制列表中包含或排除哪些标签，以及列表是否仅包含当前范围内的页面。此外，列表可以覆盖全局配置中的某些值。

¥This setting is solely provided for convenience to disable the rendering of tags and listings with a single setting (e.g. by using an environment variable), while keeping the export functionality:

可用的设置如下：

¥This will automatically disable the tags and listings settings.

`scope`¶

¥scope¶

9.6.0错误

¥The following properties are available:

此设置指定列表是否仅应考虑列表所嵌入页面的文档当前子部分内的页面：

¥8.2.0

Inline usageUsage in mkdocs.yml

<!-- material/tags { scope: true } -->

plugins:
  - tags:
      listings_map:
        custom-id:
          scope: false

然后，只需引用列表标识符：

¥Use this property to associate a page with one or more tags, making the page appear in the generated tags index. Tags are defined as a list of strings (whitespaces are allowed):

<!-- material/tags custom-id -->

`shadow`¶

¥shadow¶

insiders-4.49.0

¥If you want to prevent accidental typos when assigning tags to pages, you can set a predefined list of allowed tags in mkdocs.yml by using the tags_allowed setting.

此设置指定列表是否应包含影子标签，这允许在每个列表的基础上覆盖全局影子设置：

¥The listings configuration controls which tags are included in or excluded from a listing and whether a listing only includes pages in the current scope. Furthermore, listings can override some values from the global configuration.

Inline usageUsage in mkdocs.yml

<!-- material/tags { shadow: true } -->

plugins:
  - tags:
      listings_map:
        custom-id:
          shadow: true

然后，只需引用列表标识符：

¥The following settings are available:

<!-- material/tags custom-id -->

`toc`¶

¥toc¶

insiders-4.48.0 listings_toc

¥9.6.0 false

此设置指定列表是否应在目录中呈现标签，从而允许在每个列表的基础上覆盖全局listings_toc设置：

¥This setting specifies whether the listing should only consider pages that are within the current subsection of the documentation of the page the listing is embedded in:

Inline usageUsage in mkdocs.yml

<!-- material/tags { toc: true } -->

plugins:
  - tags:
      listings_map:
        custom-id:
          toc: true

然后，只需引用列表标识符：

¥Then, just reference the listing identifier:

<!-- material/tags custom-id -->

`include`¶

¥include¶

9.6.0

¥ insiders-4.49.0

使用此设置可指定列表中应包含哪些标签。每个包含此设置所含标签的页面都会列在相应的标签下：

¥This setting specifies whether the listing should include shadow tags, which allows to override the global shadow setting on a per-listing basis:

Inline usageUsage in mkdocs.yml

<!-- material/tags { include: [foo, bar] } -->

plugins:
  - tags:
      listings_map:
        custom-id:
          include:
            - foo
            - bar

然后，只需引用列表标识符：

¥Then, just reference the listing identifier:

<!-- material/tags custom-id -->

如果此设置留空，则包含所有标签和页面。

¥ insiders-4.48.0 listings_toc

`exclude`¶

¥exclude¶

9.6.0

¥This setting specifies whether the listing should render tags inside the table of contents, allowing to override the global listings_toc setting on a per-listing basis:

使用此设置可指定应从列表中排除哪些标签。所有包含此设置所含标签的页面都将完全从列表中排除：

¥Then, just reference the listing identifier:

Inline usageUsage in mkdocs.yml

<!-- material/tags { exclude: [foo, bar] } -->

plugins:
  - tags:
      listings_map:
        custom-id:
          exclude:
            - foo
            - bar

然后，只需引用列表标识符：

¥9.6.0

<!-- material/tags custom-id -->

如果此设置留空，则不会排除任何标签或页面。

¥Use this setting to specify which tags should be included in the listing. Each page that features a tag that is part of this setting, is listed under the respective tag:

限制¶

¥Limitations¶

由于 MkDocs 的架构，标签插件的实现比较棘手。需要注意的是，标签列表标记不能出现在代码块内。更多技术细节，请参阅#8114 。

¥Then, just reference the listing identifier: