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>

1 files changed, 8 insertions, 4 deletions

diff --git a/packages/integrations/markdoc/src/runtime.ts b/packages/integrations/markdoc/src/runtime.ts
index f62bcec1a..44c232b79 100644
--- a/packages/integrations/markdoc/src/runtime.ts
+++ b/packages/integrations/markdoc/src/runtime.ts
@@ -19,8 +19,9 @@ import type { MarkdocIntegrationOptions } from './options.js';
 export async function setupConfig(
 	userConfig: AstroMarkdocConfig = {},
 	options: MarkdocIntegrationOptions | undefined,
+	experimentalHeadingIdCompat: boolean,
 ): Promise<MergedConfig> {
-	let defaultConfig: AstroMarkdocConfig = setupHeadingConfig();
+	let defaultConfig: AstroMarkdocConfig = setupHeadingConfig(experimentalHeadingIdCompat);
 
 	if (userConfig.extends) {
 		for (let extension of userConfig.extends) {
@@ -45,8 +46,9 @@ export async function setupConfig(
 export function setupConfigSync(
 	userConfig: AstroMarkdocConfig = {},
 	options: MarkdocIntegrationOptions | undefined,
+	experimentalHeadingIdCompat: boolean,
 ): MergedConfig {
-	const defaultConfig: AstroMarkdocConfig = setupHeadingConfig();
+	const defaultConfig: AstroMarkdocConfig = setupHeadingConfig(experimentalHeadingIdCompat);
 
 	let merged = mergeConfig(defaultConfig, userConfig);
 
@@ -168,12 +170,13 @@ export function createGetHeadings(
 	stringifiedAst: string,
 	userConfig: AstroMarkdocConfig,
 	options: MarkdocIntegrationOptions | undefined,
+	experimentalHeadingIdCompat: boolean,
 ) {
 	return function getHeadings() {
 		/* Yes, we are transforming twice (once from `getHeadings()` and again from <Content /> in case of variables).
 			TODO: propose new `render()` API to allow Markdoc variable passing to `render()` itself,
 			instead of the Content component. Would remove double-transform and unlock variable resolution in heading slugs. */
-		const config = setupConfigSync(userConfig, options);
+		const config = setupConfigSync(userConfig, options, experimentalHeadingIdCompat);
 		const ast = Markdoc.Ast.fromJSON(stringifiedAst);
 		const content = Markdoc.transform(ast as Node, config as ConfigType);
 		let collectedHeadings: MarkdownHeading[] = [];
@@ -189,12 +192,13 @@ export function createContentComponent(
 	options: MarkdocIntegrationOptions | undefined,
 	tagComponentMap: Record<string, AstroInstance['default']>,
 	nodeComponentMap: Record<NodeType, AstroInstance['default']>,
+	experimentalHeadingIdCompat: boolean,
 ) {
 	return createComponent({
 		async factory(result: any, props: Record<string, any>) {
 			const withVariables = mergeConfig(userConfig, { variables: props });
 			const config = resolveComponentImports(
-				await setupConfig(withVariables, options),
+				await setupConfig(withVariables, options, experimentalHeadingIdCompat),
 				tagComponentMap,
 				nodeComponentMap,
 			);