Predefined tag lists per plugin/preset

[mambax]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

Instead of picking tags for blogs and docs randomly, it would be nice to have a predefined set of tags where the writers can only choose from.

Has this been requested on Canny?

No response

Motivation

To our docs contribute now more than 40 people. They all love tags in docs and blogs. The issue arising is that we have the same tag multiple times, like

infra-as-code
infra as code
infrastructure as code
infrastructure-as-code

API design

Allow a tags.yml (or a tagsFilePath) to be assigned to each plugin/preset.

[
      '@docusaurus/plugin-content-blog',
      {
        id: 'cookbook',
        routeBasePath: 'cookbook',
        path: 'cookbook',
        blogSidebarCount: 'ALL',
        blogSidebarTitle: 'All recipes',
        authorsMapPath: '../authors.yml',
        tagsFilePath: '../tagsFile.yml',
        editUrl: ...,
    ],

tagsFile.yml

tags:
  - infrastructure-as-code
  - kubernetes

• If then users add tags to docs/blog that are not present in the list, the build fails (optionally, warns).
• If the file is not specified, the current approach would apply
• This would be similar to the global authors approach where you have only 1 author file

Have you tried building it?

No.

Self-service

• [X] I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

Haha, I just meant are you willing to implement this yourself... Sorry for not making it clear. Go ahead then and we can improve on your PR once it's there. Good luck!😉

[Josh-Cena]

Also, just as a tip but you'll probably realize as you work on it: we want a tag list per plugin since plugins don't share their tags. It would be cool if they do (IMO) but it's going to be very hard, so just doing it like the blog authors is fine.

[mambax]

we want a tag list per plugin Me too 🤝 I derived it from the global authors feature (not that I write it it's partially global).

[slorber]

Great feature that we indeed need, and gives the opportunity to add extra metadata to each tag in a centralized way. (we have a weird API now, as a tag can specify its page url with frontmatter, leading to potential conflicting declarations)

Agree that a config per plugin instance is preferable for now.

If then users add tags to docs/blog that are not present in the list, the build fails (optionally, warns).

We don't have that for blog authors currently, but that makes sense. However, we should rather make this opt-in and add the ability to disable this "security", as mixing inline authors/tags with registered global tags should be allowed.

Config can match onBrokenLinks union type values and be consistent for docs + blog.

@Josh-Cena what about implementing this security for blog authors first (simpler), so that we have an example to port this to tags in a consistent way? (I mean, the ability to "prevent" the usage of inline frontmatter authors)

[Josh-Cena]

what about implementing this security for blog authors first (simpler), so that we have an example to port this to tags in a consistent way? (I mean, the ability to "prevent" the usage of inline frontmatter authors)

That sounds good. We also have #5568 which I think should be of high priority as well. I don't have a solid idea of how the createFrontMatter callback is going to implemented, I'll look into it this week. I imagine the tags list API to be a little different after createFrontMatter landed.

Note in the case of authors we started a new API called authors instead of patching the old author API, but in this case we would have to patch the tags front matter. I would actually prefer that we make breaking changes and move the tags system to "global" entirely because tags are intended to be shared while authors are not. Maybe we can make a CLI command in the blog plugin to generate the tags list file & authors file?

[slorber]

but in this case we would have to patch the tags front matter.

The tags frontmatter allows a list of tags, or a list of tag objects. I'm 👍 to remove the tags object syntax, and I suspect it's not even widely used.

I would actually prefer that we make breaking changes and move the tags system to "global" entirely because tags are intended to be shared while authors are not

Not sure it's a good idea. As a simple site owner, using basic tag strings is enough and I don't necessarily want to customize a tag's description, permalink and whatever we add on this config file.

Maybe we can make a CLI command in the blog plugin to generate the tags list file & authors file?

I'd rather not introduce such CLI unless some users clearly express why it's painful to manually migrate to the new config system, considering the old one will keep working as before. It's a one-step process and should be ok IMHO

[cerkiewny]

Just an idea but, wouldn't it be useful to allow lists of similar words per line and have resolution to first one?

Something like: infrastructure, Infrastructure, infra, infr

And if you use infra you get warning saying "use tag 'infrastructure' instead of infra", but if it isn't on the list altogether you get different warning.

[slorber]

You want to declare tag aliases somehow? and normalize them?

Maybe but this can come after if we feel it's useful once we have the basic tags system in place

[Josh-Cena]

Not sure it's a good idea. As a simple site owner, using basic tag strings is enough and I don't necessarily want to customize a tag's description, permalink and whatever we add on this config file.

Over the long term string tags are not maintainable exactly because of these slight spelling differences. I already stumbled upon this in my ten-post blog. Authors are fine to be repeated on every page, but tags are meant to be used to group posts and are almost certainly reused a lot. Using only a global configuration catches these errors in an early stage.

I'd also wish that we can keep the current API for *very* casual users, but we can't have an alternative API without inventing verbose names like tag_ids which I don't like🤷‍♂️

[cerkiewny]

You want to declare tag aliases somehow? and normalize them?

Maybe but this can come after if we feel it's useful once we have the basic tags system in place

I am just worried that if you only have list, it promotes the approach of "see the warning about non existing tag? -> Add it to the tags.txt file (or however the tags are stored)".

But if you have the list of words you know and some of them are rejected because it is known that the different spelling/different form should be used. It gives users more robust checks. And the implementation is pretty much identical.

In terms of Aliases, I wouldn't go as far as creating anything beyond checks. I would just emit warnings / errors saying "you used word infra, which tag system knows about and it prohibits, because the proper replacement is infrastructure". It would be up to user to decide if he wants to create a new tag, or correct the tag to the one suggested by group.

[mambax]

Sorry to ask so dumbly, but should I still try to self-service or maybe wait until the plan is set? 😊

[Josh-Cena]

but should I still try to self-service or maybe wait until the plan is set?

You can go ahead and make an initial example so we have some solid code to discuss on, better than discussing in vacuum

[mambax]

I hope my question is not too trivial, would you mind poking me to the right direction? https://github.com/facebook/docusaurus/pull/5975

[Josh-Cena]

After some pondering I think a good middleground would be:

• Keep legacy behavior when there's no tags.yml: front matter tags are seen as array of tag labels.
• As soon as there's a tags.yml file, the tags front matter would only accept strings instead of Tag objects. Every string would be a key in the tags.yml file, and if not found, Docusaurus errors.

[OzakIOne]

I'll work on this the plan for now according to previous comments [comment 1, comment 2] is :

tags.yml will be in this format :

release:
  label: release
  description: xxx
i18n:
  label: i18n
  description: xxx
open:
  label: Open Source
  description: xx

• Keep legacy behavior when there's no tags.yml: front matter tags are seen as array of tag labels.
• As soon as there's a tags.yml file, the tags front matter would only accept strings instead of Tag objects. Every string would be a key in the tags.yml file, and if not found, Docusaurus errors.

Just like authors, you can then reference them in docs/blog using keys:

---
tags: [release, i18n, open] # this is the key in tags.yml not the label
---

In this case, these strings are keys, not labels. If there isn't a matching key in the tags definition, Docusaurus would frown at you.

There will be an option tagsFilePath in plugin-content-blog

There will be an option to configure either ignore warn or error when an unknown tag is used

I don't think there is any plans for tag synonyms resolution for now, maybe we'll consider something in the future once this one is finished

If there is anything to reconsider in this plan feel free to reply @mambax @Josh-Cena