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¶
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¶
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:
-
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.
Simpler organization and management of tags in different subsections
-
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
Configuration¶
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.
General¶
The following settings are available:
enabled¶
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:
Tags¶
The following settings are available for tags:
tags¶
9.2.9 true
Use this setting to enable or disable handling of tags. Currently, the plugin's sole purpose is to process tags, so it's equivalent to the enabled setting, but in the future, other features might be added. If you want to disable handling of tags, use:
tags_file¶
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:
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.
The provided path is resolved from the docs directory.
tags_extra_files¶
Use this setting to specify the locations of additional tags indexes, which are pages that render a subset of the tags index, in order to provide scoped tags indexes for specific sections:
plugins:
- tags:
tags_extra_files:
extra-1.md: [tag-id-1, tag-id-2, ...]
extra-2.md: [tag-id-3, tag-id-4, ...]
...
The provided path is resolved from the docs directory.
tags_slugify¶
Use this setting to change the function to use for generating URL-compatible slugs from tags. Python Markdown Extensions comes with a Unicode-aware slugify function:
When your project features non-European languages, it's advisable to use this configuration. Of course, you can also provide a custom slugification function for more granular control.
tags_slugify_separator¶
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., _:
tags_compare¶
Use this setting to specify a custom function for comparing tags. By default, tag comparison is case-sensitive, but you can use the casefold function for case-insensitive comparison:
You can also define your own comparison function, which must return a string representing the tag, that is used for sorting, and reference it in tags_compare.
tags_compare_reverse¶
insiders-4.26.2 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:
tags_pages_compare¶
Use this setting to specify a custom function for comparing pages. By default, pages occur in order of appearance, but you can sort them by using the following configuration:
You can also define your own comparison function, which must return a string representing the page, that is used for sorting, and reference it in tags_pages_compare.
tags_pages_compare_reverse¶
insiders-4.39.0 false
Use this setting to reverse the order in which pages are sorted when comparing them. By default, pages are sorted in ascending order, but you can reverse ordering as follows:
tags_allowed¶
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.
Usage¶
Metadata¶
The following properties are available:
tags¶
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):
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.