[Docs Site] Support group badges with new frontmatter property (#17032)

* [Docs Site] Support group badges with new frontmatter property

* Style guide changes

Author: KianNH

src/components/overrides/Sidebar.astro

@@ -86,6 +86,7 @@ async function handleGroup(group: Group): Promise<SidebarEntry> {
 
 	group.label = frontmatter.sidebar.group?.label ?? frontmatter.title;
 	group.order = frontmatter.sidebar.order ?? Number.MAX_VALUE;
+	group.badge = frontmatter.sidebar.group?.badge;
 
 	if (frontmatter.hideChildren) {
 		return {

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

@@ -4,9 +4,6 @@ description: |
     You can customize individual Markdown and MDX pages in Starlight by setting values in their frontmatter.
     For example, a regular page might set title and description fields.
 sidebar:
-    badge:
-        variant: tip
-        text: New!
     order: 3
 banner:
     content: |
@@ -25,10 +22,7 @@ description: |
     You can customize individual Markdown and MDX pages in Starlight by setting values in their frontmatter.
     For example, a regular page might set title and description fields.
 sidebar:
-    label: Overview
-    badge:
-        variant: tip
-        text: New!
+    order: 3
 banner:
     content: |
         <h2>Hello, world!</h2>

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

@@ -157,3 +157,40 @@ Since these pages are still accessible via other links and directly navigating t
 ### Hiding child pages of a group
 
 To make a group render as if it was a single page, which links to the index page, use the top-level `hideChildren` property.
+
+## Badges
+
+### Links
+
+To specify a badge next to the link, use the `sidebar.badge` property.
+
+```mdx title="/src/content/docs/examples/example.mdx"
+---
+title: Example
+sidebar:
+  badge: New!
+---
+```
+
+<FileTree>
+- Examples
+  - Example [New!]
+</FileTree>
+
+### Groups
+
+To specify a badge next to the group label, use the `sidebar.group.badge` inside the group's `index.mdx` frontmatter.
+
+```mdx title="/src/content/docs/examples/index.mdx"
+---
+title: Examples
+sidebar:
+  group:
+    badge: New!
+---
+```
+
+<FileTree>
+- Examples [New!]
+  - Example
+</FileTree>

src/schemas/base.ts

@@ -1,4 +1,5 @@
 import { z } from "astro:schema";
+import { BadgeConfigSchema } from "./types/badge";
 
 const spotlightAuthorDetails = z
 	.object({
@@ -89,6 +90,7 @@ export const baseSchema = z.object({
 						.describe(
 							"Hides the index page from the sidebar. Refer to https://developers.cloudflare.com/style-guide/frontmatter/sidebar/.",
 						),
+					badge: BadgeConfigSchema(),
 				})
 				.optional(),
 		})

src/schemas/types/badge.ts

@@ -0,0 +1,40 @@
+// Vendored from https://github.com/withastro/starlight/blob/a171a996b842f1fdb37a0bdbb2c9d86e1073e1a4/packages/starlight/schemas/badge.ts#
+import { z } from 'astro:schema';
+
+const badgeBaseSchema = z.object({
+	variant: z.enum(['note', 'danger', 'success', 'caution', 'tip', 'default']).default('default'),
+	class: z.string().optional(),
+});
+
+const badgeSchema = badgeBaseSchema.extend({
+	text: z.string(),
+});
+
+const i18nBadgeSchema = badgeBaseSchema.extend({
+	text: z.union([z.string(), z.record(z.string())]),
+});
+
+export const BadgeComponentSchema = badgeSchema
+	.extend({
+		size: z.enum(['small', 'medium', 'large']).default('small'),
+	})
+	.passthrough();
+
+export type BadgeComponentProps = z.input<typeof BadgeComponentSchema>;
+
+export const BadgeConfigSchema = () =>
+	z
+		.union([z.string(), badgeSchema])
+		.transform((badge) => {
+			if (typeof badge === 'string') {
+				return { variant: 'default' as const, text: badge };
+			}
+			return badge;
+		})
+		.optional();
+
+export const I18nBadgeConfigSchema = () => z.union([z.string(), i18nBadgeSchema]).optional();
+
+export type Badge = z.output<typeof badgeSchema>;
+export type I18nBadge = z.output<typeof i18nBadgeSchema>;
+export type I18nBadgeConfig = z.output<ReturnType<typeof I18nBadgeConfigSchema>>;