[Docs Site] Support custom heading IDs with MDX comments (#17551)

* [Docs Site] Support custom heading IDs with MDX comments

* Amend AnchorHeading usage guidance

* include rehype-slug behaviour, move to individual file

Author: KianNH

astro.config.ts

@@ -4,7 +4,6 @@ import tailwind from "@astrojs/tailwind";
 import starlightDocSearch from "@astrojs/starlight-docsearch";
 import starlightImageZoom from "starlight-image-zoom";
 import liveCode from "astro-live-code";
-import rehypeSlug from "rehype-slug";
 import rehypeMermaid from "rehype-mermaid";
 import rehypeAutolinkHeadings, {
 	type Options as rehypeAutolinkHeadingsOptions,
@@ -17,6 +16,7 @@ import icon from "astro-icon";
 import sitemap from "@astrojs/sitemap";
 import react from "@astrojs/react";
 import rehypeTitleFigure from "rehype-title-figure";
+import rehypeHeadingSlugs from "./plugins/rehype/heading-slugs";
 
 const runLinkCheck = process.env.RUN_LINK_CHECK || false;
 
@@ -95,7 +95,7 @@ export default defineConfig({
 					rel: ["noopener"],
 				},
 			],
-			rehypeSlug,
+			rehypeHeadingSlugs,
 			[rehypeAutolinkHeadings, autolinkConfig],
 			// @ts-expect-error TODO: fix types
 			rehypeTitleFigure,

package-lock.json

@@ -69,7 +69,6 @@
 		"rehype-autolink-headings": "^7.1.0",
 		"rehype-external-links": "^3.0.0",
 		"rehype-mermaid": "^2.1.0",
-		"rehype-slug": "^6.0.0",
 		"rehype-title-figure": "^0.1.2",
 		"sharp": "^0.33.5",
 		"solarflare-theme": "^0.0.2",
@@ -81,6 +80,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"

package.json

@@ -0,0 +1,35 @@
+import { toString } from "hast-util-to-string";
+import { visit } from "unist-util-visit";
+import GithubSlugger from "github-slugger";
+
+const slugs = new GithubSlugger();
+
+// # foo {/*bar*/} = <a id="bar">foo</a>
+export default function () {
+	return function (tree: any) {
+		slugs.reset();
+
+		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 = slugs.slug(id);
+
+					const text = element.children.at(-2);
+					text.value = text.value.trimEnd();
+					element.children.with(-2, text);
+				} else {
+					if (!element.properties.id) {
+						element.properties.id = slugs.slug(toString(element));
+					}
+				}
+			}
+		});
+	};
+}

plugins/rehype/heading-slugs.ts

@@ -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