update tags docs and error

Author: KianNH

src/components/TagsUsage.astro

@@ -1,5 +1,7 @@
 ---
 import { getCollection } from "astro:content";
+import { tags as allowedTags } from "~/schemas/tags";
+
 import AnchorHeading from "./AnchorHeading.astro";
 import Details from "./Details.astro";
 
@@ -13,28 +15,57 @@ for (const entry of entries) {
 		byTag[tag].push(entry.id);
 	}
 }
+
+const flattened = Object.values(allowedTags).flat();
 ---
 
 {
 	Object.entries(byTag)
 		.sort()
-		.map(([tag, pages]) => (
-			<>
-				<AnchorHeading depth={3} title={tag} />
-				<p>
-					<code>{tag}</code> is used on <code>{pages.length}</code> pages.
-				</p>
-				<Details header={`Pages tagged with ${tag}`}>
-					<ul>
-						{pages.map((path) => (
+		.map(([tag, pages]) => {
+			const pretty = flattened.find(
+				(x) =>
+					x.label.toLowerCase() === tag.toLowerCase() ||
+					x.variants?.find((v) => v.toLowerCase() === tag.toLowerCase()),
+			);
+
+			if (!pretty) {
+				throw new Error(
+					`[TagsUsage] Tag ${tag} not found in /src/schemas/tags.ts`,
+				);
+			}
+
+			return (
+				<>
+					<AnchorHeading depth={3} title={pretty.label} />
+					{pretty.variants && pretty.variants.length > 0 && (
+						<p>
+							Variants:
+						</p>
+						<ul>
+							{pretty.variants?.map((variant) => (
 							<li>
-								<a href={`/${path}/`} target="_blank">
-									{path}
-								</a>
+								<code>{variant}</code>
 							</li>
 						))}
 					</ul>
-				</Details>
-			</>
-		))
+				)}
+				<p>
+					Used on <code>{pages.length}</code>{" "}
+					pages.
+				</p>
+				<Details header={`Pages tagged with ${pretty.label}`}>
+					<ul>
+							{pages.map((path) => (
+								<li>
+									<a href={`/${path}/`} target="_blank">
+										{path}
+									</a>
+								</li>
+							))}
+						</ul>
+					</Details>
+				</>
+			);
+		})
 }

src/content/docs/style-guide/frontmatter/tags.mdx

@@ -6,7 +6,7 @@ import { TagsUsage } from "~/components";
 
 Tags are currently used to filter content in the [`ExternalResources`](/style-guide/components/external-resources/), [`ProductsByTag`](/style-guide/components/products-by-tag/) and the [`ResourcesBySelector`](/style-guide/components/resources-by-selector/) components.
 
-## Examples
+## Example
 
 ```mdx
 ---
@@ -17,6 +17,15 @@ tags:
 ---
 ```
 
-## Tags
+## Allowed tags and where they are being used
 
-<TagsUsage />
+Tags are validated against an allowlist in [`/src/schemas/tags.ts`](https://github.com/cloudflare/cloudflare-docs/blob/production/src/schemas/tags.ts) which defines the user-facing representation (`label`) and any associated variants.
+
+The matching is case-insensitive. For example, all of the following values are accepted in the `tags` frontmatter array and will be transformed into `Node.js`:
+
+- `node.js`
+- `NoDe.JS`
+- `node`
+- `nodejs`
+
+<TagsUsage />

src/plugins/starlight/route-data.ts

@@ -17,7 +17,7 @@ export const onRequest = defineRouteMiddleware(({ locals }) => {
 
 			if (!match) {
 				throw new Error(
-					`Invalid tag on ${entry.id}: ${tag}, please refer to the allowlist in /src/schemas/tags.ts`,
+					`Invalid tag on ${entry.id}: ${tag}, please refer to the style guide: https://developers.cloudflare.com/style-guide/frontmatter/tags/`,
 				);
 			}