Predefined tag lists per plugin/preset

[mambax]

Have you read the Contributing Guidelines on issues?

• 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

• 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.