Add `experimental.headingIdCompat` flag (#13352)

* Add `experimental.headingIdCompat` option schema & types

* Markdown and MDX support

* Markdoc support

* Add changeset

* Fix missing argument in Markdoc integration

* Improve JSDoc comment

Co-authored-by: Matt Kane <m@mk.gg>

* Refactor to avoid global context object in Markdoc

* Minor changeset tweak

* Make `rehypeHeadingIds()` argument optional for backwards compatibility

* Add doc comment to `rehypeHeadingIds()`

* Document rehype plugin usage in changeset

---------

Co-authored-by: Matt Kane <m@mk.gg>

3 files changed, 16 insertions, 4 deletions

diff --git a/packages/integrations/mdx/src/index.ts b/packages/integrations/mdx/src/index.ts
index fd2fab8c8..fe2cbde0b 100644
--- a/packages/integrations/mdx/src/index.ts
+++ b/packages/integrations/mdx/src/index.ts
@@ -101,6 +101,7 @@ export default function mdx(partialMdxOptions: Partial<MdxOptions> = {}): AstroI
 				Object.assign(vitePluginMdxOptions, {
 					mdxOptions: resolvedMdxOptions,
 					srcDir: config.srcDir,
+					experimentalHeadingIdCompat: config.experimental.headingIdCompat,
 				});
 				// @ts-expect-error After we assign, we don't need to reference `mdxOptions` in this context anymore.
 				// Re-assign it so that the garbage can be collected later.
diff --git a/packages/integrations/mdx/src/plugins.ts b/packages/integrations/mdx/src/plugins.ts
index e1640238f..c44c8fffd 100644
--- a/packages/integrations/mdx/src/plugins.ts
+++ b/packages/integrations/mdx/src/plugins.ts
@@ -23,12 +23,13 @@ const isPerformanceBenchmark = Boolean(process.env.ASTRO_PERFORMANCE_BENCHMARK);
 
 interface MdxProcessorExtraOptions {
 	sourcemap: boolean;
+	experimentalHeadingIdCompat: boolean;
 }
 
 export function createMdxProcessor(mdxOptions: MdxOptions, extraOptions: MdxProcessorExtraOptions) {
 	return createProcessor({
 		remarkPlugins: getRemarkPlugins(mdxOptions),
-		rehypePlugins: getRehypePlugins(mdxOptions),
+		rehypePlugins: getRehypePlugins(mdxOptions, extraOptions),
 		recmaPlugins: mdxOptions.recmaPlugins,
 		remarkRehypeOptions: mdxOptions.remarkRehype,
 		jsxImportSource: 'astro',
@@ -57,7 +58,10 @@ function getRemarkPlugins(mdxOptions: MdxOptions): PluggableList {
 	return remarkPlugins;
 }
 
-function getRehypePlugins(mdxOptions: MdxOptions): PluggableList {
+function getRehypePlugins(
+	mdxOptions: MdxOptions,
+	{ experimentalHeadingIdCompat }: MdxProcessorExtraOptions,
+): PluggableList {
 	let rehypePlugins: PluggableList = [
 		// ensure `data.meta` is preserved in `properties.metastring` for rehype syntax highlighters
 		rehypeMetaString,
@@ -84,7 +88,10 @@ function getRehypePlugins(mdxOptions: MdxOptions): PluggableList {
 	if (!isPerformanceBenchmark) {
 		// getHeadings() is guaranteed by TS, so this must be included.
 		// We run `rehypeHeadingIds` _last_ to respect any custom IDs set by user plugins.
-		rehypePlugins.push(rehypeHeadingIds, rehypeInjectHeadingsExport);
+		rehypePlugins.push(
+			[rehypeHeadingIds, { experimentalHeadingIdCompat }],
+			rehypeInjectHeadingsExport,
+		);
 	}
 
 	rehypePlugins.push(
diff --git a/packages/integrations/mdx/src/vite-plugin-mdx.ts b/packages/integrations/mdx/src/vite-plugin-mdx.ts
index 869c65d26..7dda9d714 100644
--- a/packages/integrations/mdx/src/vite-plugin-mdx.ts
+++ b/packages/integrations/mdx/src/vite-plugin-mdx.ts
@@ -9,6 +9,7 @@ import { safeParseFrontmatter } from './utils.js';
 export interface VitePluginMdxOptions {
 	mdxOptions: MdxOptions;
 	srcDir: URL;
+	experimentalHeadingIdCompat: boolean;
 }
 
 // NOTE: Do not destructure `opts` as we're assigning a reference that will be mutated later
@@ -61,7 +62,10 @@ export function vitePluginMdx(opts: VitePluginMdxOptions): Plugin {
 
 			// Lazily initialize the MDX processor
 			if (!processor) {
-				processor = createMdxProcessor(opts.mdxOptions, { sourcemap: sourcemapEnabled });
+				processor = createMdxProcessor(opts.mdxOptions, {
+					sourcemap: sourcemapEnabled,
+					experimentalHeadingIdCompat: opts.experimentalHeadingIdCompat,
+				});
 			}
 
 			try {