[Docs Site] Support custom heading IDs with MDX comments

astro.config.ts

@@ -17,6 +17,7 @@ import icon from "astro-icon";
 import sitemap from "@astrojs/sitemap";
 import react from "@astrojs/react";
 import rehypeTitleFigure from "rehype-title-figure";
+import { visit } from "unist-util-visit";
 
 const runLinkCheck = process.env.RUN_LINK_CHECK || false;
 
@@ -70,6 +71,30 @@ const autolinkConfig: rehypeAutolinkHeadingsOptions = {
 	content: () => [AnchorLinkIcon],
 };
 
+// # foo {/*bar*/} = <a id="bar">foo</a>
+function rehypeCustomHeadingId() {
+	return function (tree: any) {
+		visit(tree, "element", function (element: any) {
+			if (/^h[1-6]$/.test(element.tagName)) {
+				const last = element.children.at(-1);
+
+				if (
+					last.type === "mdxTextExpression" &&
+					last.value.startsWith("/*") &&
+					last.value.endsWith("*/")
+				) {
+					const id = last.value.slice(2, -2).trim();
+					element.properties.id = id;
+
+					const text = element.children.at(-2);
+					text.value = text.value.trimEnd();
+					element.children.with(-2, text);
+				}
+			}
+		});
+	};
+}
+
 // https://astro.build/config
 export default defineConfig({
 	site: "https://developers.cloudflare.com",
@@ -95,6 +120,7 @@ export default defineConfig({
 					rel: ["noopener"],
 				},
 			],
+			rehypeCustomHeadingId,
 			rehypeSlug,
 			[rehypeAutolinkHeadings, autolinkConfig],
 			// @ts-expect-error TODO: fix types

package.json

@@ -81,6 +81,7 @@
 		"tippy.js": "^6.3.7",
 		"tsx": "^4.19.1",
 		"typescript": "^5.5.4",
+		"unist-util-visit": "^5.0.0",
 		"vitest": "2.0.5",
 		"wrangler": "^3.78.10",
 		"yaml": "^2.5.1"

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

@@ -17,7 +17,17 @@ import { AnchorHeading } from "~/components";
 
 Markdown files (including partials) have this behavior by default, applied via rehype plugins. Therefore, the `AnchorHeading` component is usually only required when writing headings yourself inside components, or when working on non-markdown files.
 
-Additionally, `AnchorHeading` is useful when rendering partial files into one location where there are duplicate headings (for example, when there are multiple H3 corresponding to `/#create` in one page). `AnchorHeading` allows you to explicitly define fragments, ensuring that each heading can be referred correctly with unique anchors.
+To override the ID given to a heading within Markdown, add an MDX comment at the end of the line:
+
+```mdx
+# foo {/*bar*/}
+```
+
+It will result in the following HTML:
+
+```html
+<a id="bar">foo</a>
+```
 
 :::note