设置标签 Tags
MkDocs 的 Material 主题增加了一流的对使用标签对页面进行分类的支持，这增加了将相关页面分组并通过搜索和专门的标签索引使它们可被发现的可能性。如果您的文档很大，标签可以帮助您更快地找到相关信息。
配置
内置 tags 插件
内置的标签插件增加了使用标签对任何页面进行分类的能力，这是页面前言部分。为了添加对标签的支持，请在 mkdocs.yml 中添加以下行：
plugins:
- tags
有关所有设置的列表，请参阅插件文档。
高级设置
以下高级设置目前仅保留给我们的赞助者。它们完全是可选的，并且只为标签插件添加了额外功能：
我们近期将会在这里添加更多设置。
标签图标和标识符
每个标签都可以与一个图标相关联，该图标随后将在标签内部呈现。在为标签分配图标之前，请通过向 mkdocs.yml 中添加以下内容，将每个标签与一个唯一标识符相关联：
extra:
tags:
<tag>: <identifier> # (1)!
1、标识符只能包含字母数字字符以及破折号和下划线。例如，如果您有一个标签 Compatibility，您可以将其标识符设置为 compat：
``` yaml
extra:
tags:
Compatibility: compat
```
标签之间可以重复使用标识符。未明确关联的标签将使用默认的标签图标，即 :material-pound:。
接下来，您可以通过在 mkdocs.yml 的 theme.icon 配置设置下添加以下行，将每个标识符与图标（甚至是自定义图标）相关联：
=== “Tag icon”
``` yaml
theme:
icon:
tag:
<identifier>: <icon> # (1)!
```
1、 输入一些关键字以使用我们的[图标搜索][icon search]功能找到完美的图标，并点击简码以将其复制到剪贴板：
<div class="mdx-iconsearch" data-mdx-component="iconsearch">
<input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="tag" />
<div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
<div class="mdx-iconsearch-result__meta"></div>
<ol class="mdx-iconsearch-result__list"></ol>
</div>
</div>
=== “Tag default icon”
``` yaml
theme:
icon:
tag:
default: <icon>
```
??? example “Expand to inspect example”
``` yaml
theme:
icon:
tag:
html: fontawesome/brands/html5
js: fontawesome/brands/js
css: fontawesome/brands/css3
extra:
tags:
HTML5: html
JavaScript: js
CSS: css
```
文章使用
添加 Tags
When the built-in tags plugin is enabled, tags can be added for a document
with the front matter tags property. Add the following lines at the top of a
Markdown file:
当启用内置标签插件时，可以通过前言（front matter）中的 tags 属性为文档添加标签。在 Markdown 文件的顶部添加以下行：
---
tags:
- HTML5
- JavaScript
- CSS
---
...
该页面现在将在主标题上方和搜索预览中显示这些标签，从而可以 通过标签查找页面 。
??? question “如何为整个文件夹设置标签?”
借助[内置meta插件][built-in meta plugin]，您可以通过在相应文件夹中创建一个包含以下内容的`.meta.yml`文件，来确保为整个部分及其所有嵌套页面设置标签：
``` yaml
tags:
- HTML5
- JavaScript
- CSS
```
`.meta.yml`中设置的标签将与页面定义的标签进行合并和去重，这意味着您可以在.meta.yml中定义公共标签，然后为每个页面添加特定标签。`.meta.yml`中的标签会被附加到页面标签之后。
添加一个 Tag 索引
内置标签插件允许定义一个文件来渲染标签索引，该文件可以是nav部分中的任何页面。要添加标签索引，请创建一个页面，例如tags.md：
# Tags
Following is a list of relevant tags:
<!-- material/tags -->
然后在mkdocs.yml 文件中，添加如下内容：
plugins:
- tags:
tags_file: tags.md # (1)!
1、 在使用Insiders时，此设置不是必需的。
请注意，tags.md的路径是相对于docs/目录的。
标签标记指定了标签索引的位置，即当页面被渲染时，它会被实际的标签索引所替换。您可以在标记之前和之后包含任意内容：
高级特性
Insiders ships a ground up rewrite of the tags plugin which is infinitely more powerful than the current version in the community edition. It allows for an arbitrary number of tags indexes (listings), scoped listings, shadow tags, nested tags, and much more.
Insiders 提供了一个 从头开始重写的标签插件，其功能比社区版的当前版本要强大得多。它允许任意数量的标签索引（列表）、范围列表、影子标签、[嵌套标签] nested tags等等。
可配置的列表
可以在mkdocs.yml中或直接在 Markdown 文档中您放置标记的位置配置列表。以下是一些示例：
-
使用范围列表：将标签索引限制为与页面所在文档的子部分处于同一级别的页面：
<!-- material/tags { scope: true } --> -
仅列出特定标签：将标签索引限制为单个或多个选定的标签，例如
Foo和Bar，排除所有其他标签：<!-- material/tags { include: [Foo, Bar] } --> -
排除具有特定标签的页面：不包括具有特定标签的页面，例如
Internal。这可以是任何标签，包括影子标签<!-- material/tags { exclude: [Internal] } --> -
在目录中启用或禁用标签：指定目录是否在最近的标题下列出所有标签：
<!-- material/tags { toc: false } -->
请参阅列表配置以了解所有选项。
范围列表
如果您的文档很大，您可能希望考虑使用范围列表，它只包括与包含列表的页面处于同一级别或更低级别的页面。只需使用：
<!-- material/tags { scope: true } -->
如果您计划使用多个范围索引，最好在 mkdocs.yml 中定义一个列表配置，然后可以通过其ID进行引用：
plugins:
- tags:
listings_map:
scoped:
scope: true
您现在可以使用：
<!-- material/tags scoped -->
影子标签
影子标签是仅用于组织的标签，可以通过一个简单的标志来包含或排除它们以进行渲染。它们可以在shadow_tags设置中进行枚举：
plugins:
- tags:
shadow_tags:
- Draft
- Internal
如果文档被标记为Draft，则该标签只有在启用shadow设置时才会被渲染，禁用时则会被排除。这为使用标签进行结构化提供了极好的机会。
嵌套标签
Insiders 提供了对嵌套标签的支持。tags_hierarchy_separator允许创建标签的层次结构，例如Foo/Bar。嵌套标签将作为父标签的子标签进行渲染：
plugins:
- tags:
tags_hierarchy: true
隐藏页面上的标签
虽然标签会在主标题上方进行渲染，但有时可能希望隐藏特定页面上的标签，这可以通过使用前言的 hide 属性来实现：
---
hide:
- tags
---
# Page title
...