[`tags` plugin] Feature suggestion: multiple tag listings (files) & tag sets

Contribution guidelines

• I’ve read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that …

• … to my best knowledge, my idea wouldn’t break something for other users
• … the documentation does not mention anything about my idea
• … there are no open or closed issues that are related to my idea

Description

In addition or as an alternative to the global tags file, larger documentation projects would hugely benefit from specialized tag listings that could be placed anywhere in the documentation.

I imagine it as follows:

1. The metadata of any .md file in the docs can include a tags_index entry.
2. The presence of the tags_index entry is mutually exclusive with the tags metadata entry.
3. The tags_index entry has a list of dictionaries with the following keys:

• where: PLACEHOLDER (optional): the placeholder which should be replaced by the tag listing, default is [TAGS], must be specified if more than one tag listings is specified
• show: RE_TAGSET (optional): a regex that defines the tags to be included in the tag listing, if absent, all tags will be listed
• hide: RE_TAGSET (optional): a regex that defines the tags to be omitted from the tag listing, if absent, no tags will be omitted

For example, a tutorials.md for could look like this:

---
tags_index: 
   - where: "[TAGS:tutbeg]"
      show: "^tutbeg:.*"
   - where: "[TAGS:tutadv]"
      show: "^tutadv:.*"
---

# Tutorials

## Tutorials for beginners

[TAGS:tutbeg]

## Advanced tutorials

[TAGS:tutadv]

If the plugin finds a .md with the tags_index metadata key, it treats it as one of the tags files where it will put the tag listing(s) in the 2nd pass.

Then, in the 2nd pass, it goes through all the tags files.

In each one, it goes through the list of tag listing discussions (the where, show and hide keys).

In the current document, it finds the placeholder specified in where, and replaces it with the tag listing specified by the show–hide set.

If show is not given, it considers all available tags. If it is given, it considers the subset of the available tags matched by the regex.

Then, if hide is not given, that’s it. If hide is given, it removes the tags matched by the regex from the considered set.

Finally, it replaces the placeholder with the tag listing of each considered tag (tag “bubble” with the links to the pages).

That’s all.

Use Cases

I believe this may be simple to implement, would still allow simple use of the tags_file config key but that config key could now be optional.

There are many use cases. Obviously more complex documentations, where a specialized tag index could serve as a kind of table of contents for a particular portion of the docs.

Or a better categorization (grouping) of tags on the listing instead of purely alphabetical. Thanks to the user of regex, the plugin would not impose a particular syntax for the tag “namespaces”.

Screenshots / Mockups

No response

[squidfunk]

@twardoch @Wolf2323 I’ve got a working prototype for multiple tags indexes ready. Expect it to land in the coming weeks!

[squidfunk]

Released as part of 8.3.9+insiders-4.20.0. Documentation is here.