🏷️ Tags plugin 2.0 – now available

[squidfunk]

Note

The new tags plugin is available as of 9.5.3+insiders-4.48.0

Hello everyone,

We're currently rethinking the tags plugin, transforming it into something much more powerful with the help of your feedback. Here's a sneak peek into the progress we've made and the innovations on the horizon:

• Inline Tag Indexes: Introducing a new feature where you can integrate tag indexes directly within your Markdown content. By simply adding an inline comment like <!-- material/tags -->, you can create a dynamic tag index within any page, offering unprecedented flexibility in how and where tags are displayed.

• Context-Aware Tag Rendering: The plugin will intelligently render tags based on their context. For instance, if a tag index is placed below an h3 heading in your Markdown file, the tags will appear with h4 styling. This ensures that the tag index naturally fits into the structure of your document, maintaining both readability and aesthetic appeal.

• Shadow Tags for Cleaner Presentations: Some tags might be necessary for organization but not ideal for display. We're looking to introduce functionality to mark certain tags as hidden. These tags can be used for internal structuring without cluttering your page, keeping the focus on the content that matters most to your readers.

• Enhanced Flexibility with Customizable Front Matter Properties: The plugin will support customizable front matter properties. This means you can run multiple instances of the tags plugin with different configurations simultaneously, allowing for more complex and nuanced tagging systems, e.g., using tags and categories alongside each other.

• Scoped Tag Listings for Large Documentations: For extensive documentation, we plan to implement a scoped mode where a tags index includes only the pages under a specific section. This feature will enable you to create specialized tags indexes for different subsections easily, improving navigation in large document sets.

• Declarative Tag Collections in mkdocs.yml: You'll be able to define named collections of tags directly in your mkdocs.yml. This feature will enable you to group tags declaratively, and these collections can then be referenced in Markdown files, combining them with other features like scope for more precise control.

• Hierarchical Tags: The plugin should allow to define nested tags, i.e., foo and foo/bar in order to build trees of tags.

• Custom Templates for Different Index Types: Recognizing that one size does not fit all, we plan to allow users to define custom templates for different types of tag indexes. This means you could have a visually distinct layout for a blog post overview compared to a regular index of pages, enhancing the visual hierarchy and user navigation.

Coming very soon

• Specialized Tag Index Syntax for Blogs and More: We're adding additional shortcode options that cater to specific types of content, such as blog posts. This could include functionality like showcasing the "most recent 3 blog posts" or generating a list of "suggested pages" based on tags, providing a more tailored and engaging user experience.
• Cross-Project Tag Integration: The plugin is set to emit a tags.json index, which can be consumed by other plugins. This opens the door for aggregating tags across different projects, fostering a more interconnected documentation ecosystem.

These enhancements aim to transform the tags plugin into a more powerful, flexible, and user-friendly tool, enhancing the overall documentation experience on MkDocs. We're excited to see how these features will be utilized to create more dynamic and interconnected content. Your feedback and ideas are always welcome as we continue to improve the MkDocs ecosystem.

Feel free to share anything that's on your mind.

[ccoenen]

I have a few tags set up for the usual tag things (public-facing organisation of similar things). But I also have a set of tags that I only use for organisation, kind of like what you describe. Let me explain:

• I use the file filter plugin and I configured it like this:

  plugins:
    - file-filter:
        enabled_on_serve: false
        exclude_tag: ["internal", "draft", "braindump", "placeholder"]

  this way, I can work on articles well in advance. I tag them with internal (long-term storage of information just for myself), draft (something nearly finished, usually the thing I am currently working on), braindump (stuff I will work on later where I currently just note stuff in a rather unstructured way to get them out of my head) and placeholder (something I might take up at some point, but that basically just serves as an empty reminder file, often while structuring whole chapters).
• I have two additional hooks that only run in development mode:
  • tag_decorator: based on the tags mentioned above, it will augment the navigation entries with simple emoji. This state will also propagate up the navigation tree, so I can see on the top level which sub-level has anything to work on. This has one further function which also modifies based on file modification, but that's not tied to tags.
  • weight_decorator adds the weight frontmatter property that mkdocs-nav-weight uses to the navigation entries.

together, they give me a nav tree like this, all emoji and numbers you see here are added automatically. None of this shows up in production (in fact, half of the articles pictured here are still being written and don't show up in production at all. Only the ✔️ articles go live).

[alexvoss]

@Guts, thought you should be aware of this and we should think about how this might impact the RSS plugin. Could open up some new opportunities? Anything (more) from your side / the side of users of the RSS plugin to help shape this functionality?

[per1234]

I would love to see support for "nested tags"/"hierarchical tags", similar to what was requested in #4839

My source content has this format:

---
tags:
  - foo/pippo
---

# Some Page

[...]

---
tags:
  - foo/pluto
---

# Another Page

[...]

Currently, this results in a tag index structure like:

• foo/pippo
  • Some Page
• foo/pluto
  • Another Page

The intention is a structure like this:

• foo
  • pippo
    • Some Page
  • pluto
    • Another Page

This slash-separated nested tag format (which was specified in #4839) is an established convention. Examples of where it is already in use:

• Obsidian
• Foam
• Bear
• vscode-nested-tags
• markdown-tags

[squidfunk]

What happens if I use the tags foo, foo/pluto and pluto? How do they relate? Are hierarchical tags a tree or a graph, i.e., are relations uni- or bidirectional?

[alexvoss]

In Obsidian, something that is tagged #foo/pluto gets found by a search for #foo but not when I search for #pluto (there is one page tagged with only #pluto). Consequently, there is a tag tree in the UI:

Obsidian also has a graph view for the pages. When I filter for #foo, I get this:

The green dots are the tags and the white ones the pages that contain them. You can see that here a distinction is made between #foo and #foo/pluto. There is no connection between the two tags, which I find a bit surprising.

[squidfunk]

Thanks for the clarification! Creating this issue already paid off by collecting additional use cases. We'll see how we can make nested tags work. IMHO, there should definitely be a relation, but I agree that it should be trees, as we already have the tags graph itself.

[Guts]

@Guts, thought you should be aware of this and we should think about how this might impact the RSS plugin. Could open up some new opportunities? Anything (more) from your side / the side of users of the RSS plugin to help shape this functionality?

Thanks for the ping @alexvoss!

On the RSS plugin side, we mainly refer to the YAML frontmatter (mkdocs.page.meta) to define the feed items categories as defined in RSS specification. User has to specify in categories option which YAML key/s the plugin should use as item's keywords/tags/category (default to None).

See the related section in plugin's documentation: https://guts.github.io/mkdocs-rss-plugin/configuration/#categories-item-categories

On the Material theme side, the documentation make some recomendations about how to use this option (https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#rss) by defining tags and categories

To sum up: for now there is no direct relationship between Material tags plugin and RSS plugin.

[squidfunk]

I second @Guts – the RSS plugin and the tags plugin are two plugins that both consume front matter properties, but for different purposes.