Is it possible to combine docs and blog tags?

[asher-floyd]

I'm working on migrating from a clunky old Wordpress site to Docusaurus. Up to this point, all of our documentation has either been on a WP page or in a blog post (though mostly in our brains as it's a very niche academic research platform). I've finished exporting and converting the existing site (shout out to the incredible wordpress-export-to-markdown!) and am left with the quandary of how to link things which can/should remain as blogposts to the relevant documentation.

My ideal end result would be having a single shared tags.yml file for both types of content and generated pages along the lines of https://my.software/tags/app1 https://my.software/tags/app2 https://my.software/tags/corefeature etc which serves as a collection for both. Is this currently feasible? Doesn't need to look pretty or have previews; a DocCardList will do the job.

[slorber]

I understand your point but it's unfortunately not really possible.

The tags for docs can be versioned, which means that these 3 pages can eventually display different tags depending on which tags a version is using:

• /docs/tags
• /docs/1.0/tags
• /docs/2.0/tags

Blog tags are rendered on a separate page: /blog/tags

I see how having "global tags" at a /tags page might be useful, but doing so lead to challenging design decisions we have to make:

• how would third-party plugins we don't know about could register global tags? we probably need a plugin API for that case?
• how would a docs tag avoid displaying duplicate tag entries for versioned docs (ie docs/1.0/page-with-tag + docs/2.0/page-with-tag
• how do we merge tags between different plugins if they overlap?
• how do we merge tags across docs versions if they have the same name but different descritions/urls?

By "merge" I mean we don't duplicate a tag entry in the list of global tags. Imagine we have a tab "XYZ" that it used by a blog post, a doc v1 and a doc v2, then we probably want a single "XYZ" tag entry and a list of 3 sub-items instead of having 3 distinct "XYZ" tags.

Also, how do we render mixed tag items (blog + docs) in a consistent way? Currently, blog render a post preview/excerp while docs only render the title/description. Mixing these representations might lead to a weird UX. If third-party plugins can contribute tag entries to this global tag pages, then how do we render them? We probably need to normalize how we render tagged items across all plugins.

---

A simple version of this feature could be to focus only on our core plugins and ignore third-party plugins. For docs, we could eventually keep only the "latest version" and ignore all the others. Still some design decisions to make to support that.

Technically, this can probably be implemented as a "global tags plugin" thanks to the allContentLoaded() hook (undocumented but exists)

[asher-floyd]

Makes total sense - thanks! Nothing more infuriating than working with an inconsistent API. I’ll just slap a link to the tags pages on the corresponding app pages and call it a day. Hopefully the searchbar will do most of the heavy lifting re user content discovery anyway.