Setting up tags¶
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.
Built-in tags plugin¶
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
For a list of all settings, please consult the plugin documentation.
Tag icons and identifiers¶
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
The identifier can only include alphanumeric characters, as well as dashes and underscores. For example, if you have a tag
Compatibility, you can set
compatas an identifier:
Identifiers can be reused between tags. Tags which are not explicitly associated will use the default tag icon which is
Next, each identifier can be associated with an icon, even a custom icon, by adding the following lines to
mkdocs.yml under the
theme.icon configuration setting:
Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:
Expand to inspect example
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:
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.
How to set tags for an entire folder?
With the help of the built-in meta plugin, you can ensure that tags are set for an entire section and all nested pages, by creating a
.meta.yml file in the corresponding folder with the following content:
The tags set in
.meta.yml are merged and deduplicated with the tags defined for a page, which means you can define common tags in
.meta.yml and then add specific tags for each page. The tags in
.meta.yml are appended.
Adding a tags index¶
Then in your
mkdocs.yml file, add the following.
Note that the path to
tags.md is relative to 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:
Hiding tags on a page¶
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 with the front matter