[Docs Site] Track component usage in style guide (#20596)

Author: KianNH

package-lock.json

@@ -74,8 +74,11 @@
 		"jsonc-parser": "3.3.1",
 		"lz-string": "1.5.0",
 		"marked": "15.0.7",
+		"mdast-util-from-markdown": "2.0.2",
+		"mdast-util-mdx": "3.0.0",
 		"mdast-util-mdx-expression": "2.0.1",
 		"mermaid": "11.4.1",
+		"micromark-extension-mdxjs": "3.0.0",
 		"node-html-parser": "7.0.1",
 		"openapi-types": "12.1.3",
 		"parse-duration": "2.1.3",

package.json

@@ -0,0 +1,40 @@
+---
+import { getComponentsUsage } from "~/util/components";
+import AnchorHeading from "./AnchorHeading.astro";
+import Details from "./Details.astro";
+
+const components = await getComponentsUsage();
+
+const alphabetical = Object.entries(components).sort(([a], [b]) =>
+	a.localeCompare(b),
+);
+---
+
+{
+	alphabetical.map(([component, usage]) => (
+		<>
+			<AnchorHeading depth={2} title={component} />
+			<p>
+				<code>{component}</code> is used <code>{usage.count}</code> times on{" "}
+				<code>{usage.pages.size}</code> pages.
+			</p>
+			<Details header={`Pages which use ${component}`}>
+				<ul>
+					{[...usage.pages].map((path) => (
+						<li>
+							<a
+								href={
+									"https://github.com/cloudflare/cloudflare-docs/blob/production/" +
+									path
+								}
+								target="_blank"
+							>
+								{path}
+							</a>
+						</li>
+					))}
+				</ul>
+			</Details>
+		</>
+	))
+}

src/components/ComponentsUsage.astro

@@ -10,6 +10,7 @@ export { default as APIRequest } from "./APIRequest.astro";
 export { default as AvailableNotifications } from "./AvailableNotifications.astro";
 export { default as CompatibilityFlag } from "./CompatibilityFlag.astro";
 export { default as CompatibilityFlags } from "./CompatibilityFlags.astro";
+export { default as ComponentsUsage } from "./ComponentsUsage.astro";
 export { default as CURL } from "./CURL.astro";
 export { default as Description } from "./Description.astro";
 export { default as Details } from "./Details.astro";

src/components/index.ts

@@ -5,15 +5,19 @@ import { marked } from "marked";
 import { Breadcrumbs } from "astro-breadcrumbs";
 import "astro-breadcrumbs/breadcrumbs.css";
 
+import { Aside } from "@astrojs/starlight/components";
 import Description from "~/components/Description.astro";
 import SpotlightAuthorDetails from "~/components/SpotlightAuthorDetails.astro";
 import LastReviewed from "~/components/LastReviewed.astro";
 
 import { getEntry } from "astro:content";
 
-const spotlightDetails = Astro.locals.starlightRoute.entry.data.spotlight;
-const updated = Astro.locals.starlightRoute.entry.data.updated;
-const summary = Astro.locals.starlightRoute.entry.data.summary;
+const frontmatter = Astro.locals.starlightRoute.entry.data;
+
+const spotlightDetails = frontmatter.spotlight;
+const updated = frontmatter.updated;
+const summary = frontmatter.summary;
+const component = frontmatter.styleGuide?.component;
 
 const slug = Astro.locals.starlightRoute.entry.slug;
 
@@ -107,6 +111,8 @@ const hideBreadcrumbs = Astro.locals.starlightRoute.hideBreadcrumbs;
 
 {summary && <Description set:html={marked.parse(summary)} />}
 
+{component && <Aside>To see a list of pages this component is used on, please visit the <a href={`/style-guide/components/usage/#${component.toLowerCase()}`}>usage page</a>.</Aside>}
+
 <style>
 	:root {
 		--color-link-breadcrumbs: var(--sl-color-text-accent);

src/components/overrides/PageTitle.astro

@@ -1,5 +1,7 @@
 ---
 title: Anchor heading
+styleGuide:
+  component: AnchorHeading
 ---
 
 The `AnchorHeading` component defines headings. Specifically, `AnchorHeading` performs the following:

src/content/docs/style-guide/components/anchor-heading.mdx

@@ -1,5 +1,7 @@
 ---
 title: API request
+styleGuide:
+  component: APIRequest
 ---
 
 ## Import

src/content/docs/style-guide/components/api-request.mdx

@@ -1,5 +1,7 @@
 ---
 title: Available notifications
+styleGuide:
+  component: AvailableNotifications
 ---
 
 ## Components

src/content/docs/style-guide/components/available-notifications.mdx

@@ -1,5 +1,7 @@
 ---
 title: Buttons
+styleGuide:
+  component: LinkButton
 ---
 
 ```mdx live

src/content/docs/style-guide/components/buttons.mdx

@@ -1,5 +1,7 @@
 ---
 title: Cards
+styleGuide:
+  component: Card
 ---
 
 Cards are a built-in component provided by [Starlight](https://starlight.astro.build/components/cards/).