template |
---|
overrides/main.html |
Material for MkDocs adds first-class support for categorizing pages with tags, which adds the possibility to group related pages and make them discoverable via search and a dedicated tags index. If your documentation is large, tags can help to discover relevant information faster.
:octicons-tag-24: 8.2.0 · :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental
The built-in tags plugin adds the ability to categorize any page with tags
as part of the front matter of the page. In order to add support for tags, add
the following lines to mkdocs.yml
:
plugins:
- tags
The following configuration options are available:
tags_file
{ #tags-file }
: :octicons-milestone-24: Default: none – This option specifies which file should be used to render the tags index. See the section on adding a tags index for more information. If this option is specified, tags will become clickable, pointing to the corresponding section in the tags index:
``` yaml
plugins:
- tags:
tags_file: tags.md
```
The page holding the tags index can be linked anywhere in the `nav` section
of `mkdocs.yml`. Note, however, that this options is not required – only use
it if you want a tags index page.
:octicons-heart-fill-24:{ .mdx-heart } Sponsors only{ .mdx-insiders } · :octicons-tag-24: insiders-4.13.0 · :octicons-beaker-24: Experimental
Each tag can be associated with an icon, which is then rendered inside the tag.
Before assigning icons to tags, associate each tag with a unique identifier,
by adding the following to mkdocs.yml
:
extra:
tags:
<tag>: <identifier> # (1)!
-
The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a tag
Compatibility
, you can setcompat
as an identifier:extra: tags: Compatibility: compat
Identifiers can be reused between tags. Tags which are not explicitly associated will use the default tag icon which is :material-pound:
Next, each identifier can be associated with an icon, or even a custom icon,
by adding the following lines to mkdocs.yml
under the theme.icon
configuration setting:
=== "Tag icon"
``` yaml
theme:
icon:
tag:
<identifier>: <icon> # (1)!
```
1. Enter a few keywords to find the perfect icon using our [icon search] and
click on the shortcode to copy it to your clipboard:
<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
```
When both, the built-in tags plugin and Metadata extension are enabled, tags can be added for a document with custom front matter. Add the following lines at the top of a Markdown file:
---
tags:
- HTML5
- JavaScript
- CSS
- Other
---
...
The page will now render with those tags above the main headline and within the search preview, which now allows to find pages by tags, as shown in the following screenshots:
=== "Tags"
[![Tags preview]][Tags preview]
=== "Tag search"
[![Tag search preview]][Tag search preview]
The built-in tags plugin allows to define a file to render a tags index
tags.tags_file, which can be any page that is part of the nav
section. To
add a tags index, create a page, e.g. tags.md
:
# Tags
Following is a list of relevant tags:
[TAGS]
The [TAGS]
marker specifies the position of the tags index, i.e. it is
replaced with the actual tags index when the page is rendered. You can include
arbitrary content before and after the marker:
While the tags are rendered above the main headline, sometimes, it might be desirable to hide them for a specific page, which can be achieved by using the Metadata extension:
---
hide:
- tags
---
# Document title
...