feat!: stabilize experimental.headingIdCompat (#14494)

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

Author: 3 people

.changeset/good-camels-pull.md

@@ -0,0 +1,24 @@
+---
+'@astrojs/markdoc': minor
+'@astrojs/mdx': major
+'@astrojs/markdown-remark': major
+'astro': major
+---
+
+Updates Markdown heading ID generation
+
+In Astro 5.x, an additional default processing step to Markdown stripped trailing hyphens from the end of IDs for section headings ending in special characters. This provided a cleaner `id` value, but could lead to incompatibilities rendering your Markdown across platforms.
+
+In Astro 5.5, the `experimental.headingIdCompat` flag was introduced to allow you to make the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm, using the popular [`github-slugger`](https://github.com/Flet/github-slugger) package.
+
+Astro 6.0 removes this experimental flag and makes this the new default behavior in Astro: trailing hyphens from the end of IDs for headings ending in special characters are no longer removed.
+
+#### What should I do?
+
+If you have manual links to headings, you may need to update some anchor link values with a new trailing hyphen. 
+
+If you were previously using this experimental feature, remove this experimental flag from your configuration.
+
+If you were previously using the `rehypeHeadingIds` plugin directly to enforce compatibility, remove the `headingIdCompat` option as it no longer exists.
+
+See the [Astro 6.0 upgrade guide](https://docs.astro.build/en/guides/upgrade-to/v6/#changed-markdown-heading-id-generation) for upgrade examples, and instructions to create a custom rehype plulgin if you want to keep the old ID generation for backward compatibility reasons.

packages/astro/src/core/config/schemas/base.ts

@@ -97,7 +97,6 @@ export const ASTRO_CONFIG_DEFAULTS = {
 	experimental: {
 		clientPrerender: false,
 		contentIntellisense: false,
-		headingIdCompat: false,
 		liveContentCollections: false,
 		csp: false,
 		chromeDevtoolsWorkspace: false,
@@ -473,10 +472,6 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentIntellisense),
-			headingIdCompat: z
-				.boolean()
-				.optional()
-				.default(ASTRO_CONFIG_DEFAULTS.experimental.headingIdCompat),
 			fonts: z.array(z.union([localFontFamilySchema, remoteFontFamilySchema])).optional(),
 			liveContentCollections: z
 				.boolean()

packages/astro/src/types/public/config.ts

@@ -2139,20 +2139,6 @@ export interface AstroUserConfig<
 		 */
 		fonts?: FontFamily[];
 
-		/**
-		 * @name experimental.headingIdCompat
-		 * @type {boolean}
-		 * @default `false`
-		 * @version 5.5.x
-		 * @description
-		 *
-		 * Enables full compatibility of Markdown headings IDs with common platforms such as GitHub and npm.
-		 *
-		 * When enabled, IDs for headings ending with non-alphanumeric characters, e.g. `<Picture />`, will
-		 * include a trailing `-`, matching standard behavior in other Markdown tooling.
-		 */
-		headingIdCompat?: boolean;
-
 		/**
 		 * @name experimental.csp
 		 * @type {boolean | object}

packages/astro/src/vite-plugin-markdown/index.ts

@@ -62,7 +62,6 @@ export default function markdown({ settings, logger }: AstroPluginOptions): Plug
 				if (!processor) {
 					processor = createMarkdownProcessor({
 						image: settings.config.image,
-						experimentalHeadingIdCompat: settings.config.experimental.headingIdCompat,
 						...settings.config.markdown,
 					});
 				}

packages/integrations/markdoc/src/content-entry-type.ts

@@ -52,7 +52,6 @@ export async function getContentEntryType({
 			const markdocConfig = await setupConfig(
 				userMarkdocConfig,
 				options,
-				astroConfig.experimental.headingIdCompat,
 			);
 			const filePath = fileURLToPath(fileUrl);
 			raiseValidationErrors({
@@ -121,7 +120,6 @@ markdocConfig.nodes = { ...assetsConfig.nodes, ...markdocConfig.nodes };
 
 ${getStringifiedImports(componentConfigByTagMap, 'Tag', astroConfig.root)}
 ${getStringifiedImports(componentConfigByNodeMap, 'Node', astroConfig.root)}
-const experimentalHeadingIdCompat = ${JSON.stringify(astroConfig.experimental.headingIdCompat || false)}
 
 const tagComponentMap = ${getStringifiedMap(componentConfigByTagMap, 'Tag')};
 const nodeComponentMap = ${getStringifiedMap(componentConfigByNodeMap, 'Node')};
@@ -132,15 +130,14 @@ const stringifiedAst = ${JSON.stringify(
 				/* Double stringify to encode *as* stringified JSON */ JSON.stringify(ast),
 			)};
 
-export const getHeadings = createGetHeadings(stringifiedAst, markdocConfig, options, experimentalHeadingIdCompat);
+export const getHeadings = createGetHeadings(stringifiedAst, markdocConfig, options);
 export const Content = createContentComponent(
 	Renderer,
 	stringifiedAst,
 	markdocConfig,
-  options,
+	options,
 	tagComponentMap,
 	nodeComponentMap,
-	experimentalHeadingIdCompat,
 )`;
 			return { code: res };
 		},

packages/integrations/markdoc/src/heading-ids.ts

@@ -11,23 +11,17 @@ function getSlug(
 	attributes: Record<string, any>,
 	children: RenderableTreeNode[],
 	headingSlugger: Slugger,
-	experimentalHeadingIdCompat: boolean,
 ): string {
 	if (attributes.id && typeof attributes.id === 'string') {
 		return attributes.id;
 	}
 	const textContent = attributes.content ?? getTextContent(children);
-	let slug = headingSlugger.slug(textContent);
-
-	if (!experimentalHeadingIdCompat) {
-		if (slug.endsWith('-')) slug = slug.slice(0, -1);
-	}
-	return slug;
+	return headingSlugger.slug(textContent);
 }
 
-type HeadingIdConfig = MarkdocConfig & {
-	ctx: { headingSlugger: Slugger; experimentalHeadingIdCompat: boolean };
-};
+interface HeadingIdConfig extends MarkdocConfig {
+	ctx: { headingSlugger: Slugger };
+}
 
 /*
 	Expose standalone node for users to import in their config.
@@ -50,12 +44,7 @@ export const heading: Schema = {
 					'Unexpected problem adding heading IDs to Markdoc file. Did you modify the `ctx.headingSlugger` property in your Markdoc config?',
 			});
 		}
-		const slug = getSlug(
-			attributes,
-			children,
-			config.ctx.headingSlugger,
-			config.ctx.experimentalHeadingIdCompat,
-		);
+		const slug = getSlug(attributes, children, config.ctx.headingSlugger);
 
 		const render = config.nodes?.heading?.render ?? `h${level}`;
 
@@ -72,12 +61,11 @@ export const heading: Schema = {
 };
 
 // Called internally to ensure `ctx` is generated per-file, instead of per-build.
-export function setupHeadingConfig(experimentalHeadingIdCompat: boolean): HeadingIdConfig {
+export function setupHeadingConfig(): HeadingIdConfig {
 	const headingSlugger = new Slugger();
 	return {
 		ctx: {
 			headingSlugger,
-			experimentalHeadingIdCompat,
 		},
 		nodes: {
 			heading,

packages/integrations/markdoc/src/runtime.ts

@@ -19,9 +19,8 @@ import type { MarkdocIntegrationOptions } from './options.js';
 export async function setupConfig(
 	userConfig: AstroMarkdocConfig = {},
 	options: MarkdocIntegrationOptions | undefined,
-	experimentalHeadingIdCompat: boolean,
 ): Promise<MergedConfig> {
-	let defaultConfig: AstroMarkdocConfig = setupHeadingConfig(experimentalHeadingIdCompat);
+	let defaultConfig: AstroMarkdocConfig = setupHeadingConfig();
 
 	if (userConfig.extends) {
 		for (let extension of userConfig.extends) {
@@ -46,9 +45,8 @@ export async function setupConfig(
 export function setupConfigSync(
 	userConfig: AstroMarkdocConfig = {},
 	options: MarkdocIntegrationOptions | undefined,
-	experimentalHeadingIdCompat: boolean,
 ): MergedConfig {
-	const defaultConfig: AstroMarkdocConfig = setupHeadingConfig(experimentalHeadingIdCompat);
+	const defaultConfig: AstroMarkdocConfig = setupHeadingConfig();
 
 	let merged = mergeConfig(defaultConfig, userConfig);
 
@@ -170,13 +168,12 @@ 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, experimentalHeadingIdCompat);
+		const config = setupConfigSync(userConfig, options);
 		const ast = Markdoc.Ast.fromJSON(stringifiedAst);
 		const content = Markdoc.transform(ast as Node, config as ConfigType);
 		let collectedHeadings: MarkdownHeading[] = [];
@@ -192,13 +189,12 @@ 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, experimentalHeadingIdCompat),
+				await setupConfig(withVariables, options),
 				tagComponentMap,
 				nodeComponentMap,
 			);

packages/integrations/markdoc/test/headings.test.js

@@ -9,38 +9,6 @@ async function getFixture(name) {
 	});
 }
 
-describe('experimental.headingIdCompat', () => {
-	let fixture;
-
-	before(async () => {
-		fixture = await loadFixture({
-			root: new URL(`./fixtures/headings/`, import.meta.url),
-			experimental: { headingIdCompat: true },
-		});
-	});
-
-	describe('dev', () => {
-		let devServer;
-
-		before(async () => {
-			devServer = await fixture.startDevServer();
-		});
-
-		after(async () => {
-			await devServer.stop();
-		});
-
-		it('applies IDs to headings containing special characters', async () => {
-			const res = await fixture.fetch('/headings-with-special-characters');
-			const html = await res.text();
-			const { document } = parseHTML(html);
-
-			assert.equal(document.querySelector('h2')?.id, 'picture-');
-			assert.equal(document.querySelector('h3')?.id, '-sacrebleu--');
-		});
-	});
-});
-
 describe('Markdoc - Headings', () => {
 	let fixture;
 
@@ -72,8 +40,8 @@ describe('Markdoc - Headings', () => {
 			const html = await res.text();
 			const { document } = parseHTML(html);
 
-			assert.equal(document.querySelector('h2')?.id, 'picture');
-			assert.equal(document.querySelector('h3')?.id, '-sacrebleu-');
+			assert.equal(document.querySelector('h2')?.id, 'picture-');
+			assert.equal(document.querySelector('h3')?.id, '-sacrebleu--');
 		});
 
 		it('generates the same IDs for other documents with the same headings', async () => {

packages/integrations/mdx/src/index.ts

@@ -101,7 +101,6 @@ 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.

packages/integrations/mdx/src/plugins.ts

@@ -23,13 +23,12 @@ 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, extraOptions),
+		rehypePlugins: getRehypePlugins(mdxOptions),
 		recmaPlugins: mdxOptions.recmaPlugins,
 		remarkRehypeOptions: mdxOptions.remarkRehype,
 		jsxImportSource: 'astro',
@@ -58,10 +57,7 @@ function getRemarkPlugins(mdxOptions: MdxOptions): PluggableList {
 	return remarkPlugins;
 }
 
-function getRehypePlugins(
-	mdxOptions: MdxOptions,
-	{ experimentalHeadingIdCompat }: MdxProcessorExtraOptions,
-): PluggableList {
+function getRehypePlugins(mdxOptions: MdxOptions): PluggableList {
 	let rehypePlugins: PluggableList = [
 		// ensure `data.meta` is preserved in `properties.metastring` for rehype syntax highlighters
 		rehypeMetaString,
@@ -88,10 +84,7 @@ function getRehypePlugins(
 	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, { experimentalHeadingIdCompat }],
-			rehypeInjectHeadingsExport,
-		);
+		rehypePlugins.push([rehypeHeadingIds], rehypeInjectHeadingsExport);
 	}
 
 	rehypePlugins.push(