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, 41 insertions, 0 deletions

diff --git a/packages/integrations/markdoc/test/headings.test.js b/packages/integrations/markdoc/test/headings.test.js
index 330d3356b..1a6061aa6 100644
--- a/packages/integrations/markdoc/test/headings.test.js
+++ b/packages/integrations/markdoc/test/headings.test.js
@@ -9,6 +9,38 @@ 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;
 
@@ -35,6 +67,15 @@ describe('Markdoc - Headings', () => {
 			idTest(document);
 		});
 
+		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-');
+		});
+
 		it('generates the same IDs for other documents with the same headings', async () => {
 			const res = await fixture.fetch('/headings-stale-cache-check');
 			const html = await res.text();