[Style Guide] Generate custom frontmatter docs

Author: KianNH

src/components/BaseSchemaProperties.astro

@@ -0,0 +1,75 @@
+---
+import { z } from "astro:schema";
+import { baseSchema } from "~/schemas";
+import { marked } from "marked";
+
+import Type from "./Type.astro";
+import MetaInfo from "./MetaInfo.astro";
+import AnchorHeading from "./AnchorHeading.astro";
+import Details from "./Details.astro";
+
+const schema = baseSchema({
+	// @ts-expect-error Normally passed in by Astro but we are using the schema standalone.
+	image: () => z.function(),
+}).shape;
+
+const getInnerType = ({ _def }: z.ZodTypeAny | z.ZodEffects<any>) => {
+	if (_def.innerType) return getInnerType(_def.innerType);
+
+	return _def;
+};
+---
+
+{
+	Object.entries(schema)
+		.sort()
+		.map(([key, outer]) => {
+			const outerType = outer._def.typeName;
+			const outerDescription = outer._def.description;
+
+			const inner = getInnerType(outer);
+			const innerType =
+				key === "preview_image"
+					? "string"
+					: inner.typeName.split("Zod")[1].toLowerCase();
+
+			return (
+				<>
+					<AnchorHeading depth={3} title={key} />
+					<p>
+						<strong>Type: </strong>
+						<Type text={innerType} />
+						{outerType === "ZodOptional" && (
+							<>
+								{" "}
+								<MetaInfo text="optional" />
+							</>
+						)}
+					</p>
+					{outerDescription && (
+						<p>
+							<strong>Description: </strong>
+							<Fragment set:html={marked.parseInline(outerDescription)} />
+						</p>
+					)}
+					{inner.typeName === "ZodUnion" && (
+						<p>
+							<Details header="Allowed values">
+								<ul>
+									{inner.options
+										.filter(
+											(option: any) => option._def.typeName === "ZodLiteral",
+										)
+										.map((option: any) => (
+											<li>
+												<code>{option._def.value}</code>
+											</li>
+										))}
+								</ul>
+							</Details>
+						</p>
+					)}
+				</>
+			);
+		})
+}

src/content/docs/style-guide/frontmatter/custom-properties.mdx

@@ -5,14 +5,10 @@ sidebar:
 ---
 
 import { Type, MetaInfo } from "~/components";
+import BaseSchemaProperties from "~/components/BaseSchemaProperties.astro";
 
-We have added specific custom [frontmatter](/style-guide/frontmatter/) to meet specific needs.
+We have added specific custom [frontmatter](/style-guide/frontmatter/) properties to meet specific needs.
 
-- `difficulty` <Type text="string" /> <MetaInfo text="optional" />: Difficulty is displayed as a column in the [ListTutorials component](/style-guide/components/list-tutorials/).
-- `external_link` <Type text="string" /> <MetaInfo text="optional" />: Path to another page in our docs or elsewhere. Used to add a crosslink entry to the lefthand navigation sidebar.
-- `pcx_content_type` <Type text="string" /> <MetaInfo text="optional" />: The purpose of the page, and defined through specific pages in [Content strategy](/style-guide/documentation-content-strategy/content-types/).
-- `preview_image` <Type text="string" /> <MetaInfo text="optional" />: An `src` path to the image that you want to use as a custom preview image for social sharing.
-- `products` <Type text="Array<String>" /> <MetaInfo text="optional" />: The names of related products, which show on some grids for Examples, [Tutorials](/style-guide/documentation-content-strategy/content-types/tutorial/), and [Reference Architectures](/style-guide/documentation-content-strategy/content-types/reference-architecture/)
-- `tags` <Type text="Array<String>" /> <MetaInfo text="optional" />: A group of related keywords relating to the purpose of the page.
-- `updated` <Type text="Date" /> <MetaInfo text="optional" />: This is used to automatically add the [LastReviewed component](/style-guide/components/last-reviewed/).
-- `noindex` <Type text="Boolean" /> <MetaInfo text="optional" />: If true, this property adds a `noindex` declaration to the page, which will tell internal / external search crawlers to ignore this page. Helpful for pages that are historically accurate, but no longer recommended, such as [Workers Sites](/workers/configuration/sites/).
+## Properties
+
+<BaseSchemaProperties />

src/schemas/base.ts

@@ -10,12 +10,16 @@ const spotlightAuthorDetails = z
 	})
 	.optional()
 	.describe(
-		"These are used to automatically add the SpotlightAuthorDetails component to the page. Refer to https://developers.cloudflare.com/style-guide/components/spotlight-author-details/.",
+		"These are used to automatically add the [SpotlightAuthorDetails component](/style-guide/components/spotlight-author-details/) to the page.",
 	);
 
 export const baseSchema = ({ image }: SchemaContext) =>
 	z.object({
-		preview_image: image().optional(),
+		preview_image: image()
+			.optional()
+			.describe(
+				"A `src` path to the image that you want to use as a custom preview image for social sharing.",
+			),
 		pcx_content_type: z
 			.union([
 				z.literal("overview"),
@@ -41,15 +45,21 @@ export const baseSchema = ({ image }: SchemaContext) =>
 			.catch((ctx) => ctx.input)
 			.optional()
 			.describe(
-				"Refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/.",
+				"The purpose of the page, and defined through specific pages in [Content strategy](/style-guide/documentation-content-strategy/content-types/).",
 			),
 		content_type: z.string().optional(),
-		tags: z.string().array().optional(),
+		tags: z
+			.string()
+			.array()
+			.optional()
+			.describe(
+				"A group of related keywords relating to the purpose of the page. Refer to [Tags](/style-guide/frontmatter/tags/).",
+			),
 		external_link: z
 			.string()
 			.optional()
 			.describe(
-				"Links to this page (i.e sidebar, directory listing) will instead appear as the provided link.",
+				"Path to another page in our docs or elsewhere. Used to add a crosslink entry to the lefthand navigation sidebar.",
 			),
 		difficulty: z
 			.union([
@@ -60,23 +70,34 @@ export const baseSchema = ({ image }: SchemaContext) =>
 			.catch((ctx) => ctx.input)
 			.optional()
 			.describe(
-				"Difficulty is displayed as a column in the ListTutorials component.",
+				"Difficulty is displayed as a column in the [ListTutorials component](/style-guide/components/list-tutorials/).",
 			),
 		updated: z
 			.date()
 			.optional()
 			.describe(
-				"This is used to automatically add the LastReviewed component to a page. Refer to https://developers.cloudflare.com/style-guide/components/last-reviewed/.",
+				"This is used to automatically add the [LastReviewed component](/style-guide/components/last-reviewed/).",
 			),
 		spotlight: spotlightAuthorDetails,
 		release_notes_file_name: z.string().array().optional(),
 		release_notes_product_area_name: z.string().optional(),
-		products: z.string().array().optional(),
+		products: z
+			.string()
+			.array()
+			.optional()
+			.describe(
+				"The names of related products, which show on some grids for Examples, [Tutorials](/style-guide/documentation-content-strategy/content-types/tutorial/), and [Reference Architectures](/style-guide/documentation-content-strategy/content-types/reference-architecture/)",
+			),
 		languages: z.string().array().optional(),
 		summary: z.string().optional(),
 		goal: z.string().array().optional(),
 		operation: z.string().array().optional(),
-		noindex: z.boolean().optional(),
+		noindex: z
+			.boolean()
+			.optional()
+			.describe(
+				"If true, this property adds a `noindex` declaration to the page, which will tell internal / external search crawlers to ignore this page. Helpful for pages that are historically accurate, but no longer recommended, such as [Workers Sites](/workers/configuration/sites/).",
+			),
 		sidebar: z
 			.object({
 				order: z.number().optional(),
@@ -93,18 +114,21 @@ export const baseSchema = ({ image }: SchemaContext) =>
 							.boolean()
 							.default(false)
 							.describe(
-								"Hides the index page from the sidebar. Refer to https://developers.cloudflare.com/style-guide/frontmatter/sidebar/.",
+								"Hides the index page from the sidebar. Refer to [Sidebar](/style-guide/frontmatter/sidebar/).",
 							),
 						badge: BadgeConfigSchema(),
 					})
 					.optional(),
 			})
-			.optional(),
+			.optional()
+			.describe(
+				"Used to configure various sidebar options. Refer to [Sidebar](/style-guide/frontmatter/sidebar/).",
+			),
 		hideChildren: z
 			.boolean()
 			.optional()
 			.describe(
-				"Renders this group as a single link on the sidebar, to the index page. Refer to https://developers.cloudflare.com/style-guide/frontmatter/sidebar/.",
+				"Renders this group as a single link on the sidebar, to the index page. Refer to [Sidebar](https://developers.cloudflare.com/style-guide/frontmatter/sidebar/).",
 			),
 		styleGuide: z
 			.object({