Tags support 🆕

[squidfunk]

EDIT: Tags support is available as of Insiders 2.7.0! Check out the demo or the docs

---

Sometimes, it might be beneficial to group documents by specific tags, especially in very large codebases. There are some prior discussions on tag support on the MkDocs issue tracker (see below) and there is mkdocs-plugin-tags, which looks abandoned. In general I would consider the following features to provide a good first implementation for tag support:

• The author can specify tags as part of the front matter of a document, exactly like in other static site generators like Jekyll.
• Tags are rendered below above the actual content of the document
• Tags are rendered inside the search and can be searched like the title and text of a document
• There's an overview page that lists all tags and related articles (as provided by mkdocs-plugin-tags)

This is a sneak peek of how I would imagine tags to work inside search:

Ohne.Titel.mp4

This is how the tags overview page will look:

This will not be an integration of the said plugin, but a standalone integration into Material for MkDocs itself, because I believe for this to be useful, it will need to be integrated deeply (search etc.).

Any feedback is appreciated!

---

Prior discussions:

• [Feature request] Tag support (again) [with arguments and explained in depth) mkdocs/mkdocs#1828
• tag and category support? mkdocs/mkdocs#1411
• Search in YAML headers mkdocs/mkdocs#1243
• Tagging support mkdocs/mkdocs#759
• Categories / Tags #1472

[Stanzilla]

Love it, things to consider:

• Mention that you have to "install" mkdocs now via ./mkdocs-material in requirements.txt when using a sub module / fork.
• It would be nice if you could adjust the place the tag gets inserted in the template without having to touch the plugin itself

[Stanzilla]

Suggestion: add tags to the list of things that hide: can hide.

[rjahern5]

I am getting some warnings in the tag implementation when build. Looks like everything 'works' fine though:

WARNING -  Documentation file 'tags.md' contains a link to 'api/some/page.html' which is not found in the documentation files. 

Looks like tags is explicitly referencing the page with the html extension instead of using md?

[squidfunk]

@rjahern5 thanks for reporting. Could you give me some more details? If you could boil it down to a reproducible case, it's probably a quick fix. Are you using use_directory_urls: false?

[rjahern5]

@squidfunk yes sir, I just created a small sample project and changed it to true but it is still giving the same issue. I will open a different ticket for it. Incredible feature and thank you!

[squidfunk]

@rjahern5 see #2638.

[squidfunk]

@rjahern5 the issue should be fixed in Insiders 2.7.2.

[Kanaduchi]

Is it possible to add Tags to some headers and not whole page?

Example, I have some page, which contains ###Header1. And I want to set tag "Deprecated" only for this header.

[squidfunk]

@Kanaduchi tags are defined on a page level, so they cannot be set for specific headers.

[Kanaduchi]

@squidfunk can it be considered as a separate enhancement? Such feature can be very useful

[squidfunk]

@Kanaduchi how would you imagine this to work, I mean from an authoring perspective? How could the Markdown look? Tags are defined in front matter, which we can only define once per document.

[squidfunk]

The latest commit on Insiders addresses the following two ideas by @Stanzilla:

1. Tags can now be hidden on any page using front matter
2. Tags are now rendered through a partial, making customization simpler. This made it necessary to render tags above the headline. If one wishes to move them below the content, this can now be done via regular theme extension.

I also adjusted the installation instructions to account for the built-in plugins which need to be installed when cloning from git.

Closing this issue. For all subsequent bug reports or feature requests, please open separate discussions or issues.