[MDX] Prevent overriding `collect-headings` plugin (#4181)

* fix: make rehypeCollectHeadings a required plugin

* docs: update README on rehypePlugins

* test: remove collect-headings override test

* docs: remove extends from rehype docs

* chore: changeset

3 files changed, 9 insertions, 30 deletions

diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md
index 5b3f12fda..86b7b6499 100644
--- a/packages/integrations/mdx/README.md
+++ b/packages/integrations/mdx/README.md
@@ -297,26 +297,11 @@ export default {
 <details>
   <summary><strong>rehypePlugins</strong></summary>
 
-**Default plugins:** [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts)
-
 [Rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md) allow you to transform the HTML that your Markdown generates. We recommend checking the [Remark plugin](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) catalog first _before_ considering rehype plugins, since most users want to transform their Markdown syntax instead. If HTML transforms are what you need, we encourage you to browse [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for a full curated list of plugins!
 
-We apply our own [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts) plugin by default. This applies IDs to all headings (i.e. `h1 -> h6`) in your MDX files to [link to headings via anchor tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page).
-
-To apply rehype plugins _while preserving_ Astro's default plugins, use a nested `extends` object like so:
+We apply our own (non-overridable) [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts) plugin. This applies IDs to all headings (i.e. `h1 -> h6`) in your MDX files to [link to headings via anchor tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page).
 
-```js
-// astro.config.mjs
-import rehypeMinifyHtml from 'rehype-minify';
-
-export default {
-  integrations: [mdx({
-    rehypePlugins: { extends: [rehypeMinifyHtml] },
-  })],
-}
-```
-
-To apply plugins _without_ Astro's defaults, you can apply a plain array:
+To apply additional rehype plugins, pass an array to the `rehypePlugins` option like so:
 
 ```js
 // astro.config.mjs
diff --git a/packages/integrations/mdx/src/index.ts b/packages/integrations/mdx/src/index.ts
index 85eec630e..2c7247237 100644
--- a/packages/integrations/mdx/src/index.ts
+++ b/packages/integrations/mdx/src/index.ts
@@ -27,8 +27,11 @@ type MdxOptions = {
 	frontmatterOptions?: RemarkMdxFrontmatterOptions;
 };
 
-const DEFAULT_REMARK_PLUGINS = [remarkGfm, remarkSmartypants];
-const DEFAULT_REHYPE_PLUGINS = [rehypeCollectHeadings];
+const DEFAULT_REMARK_PLUGINS: MdxRollupPluginOptions['remarkPlugins'] = [
+	remarkGfm,
+	remarkSmartypants,
+];
+const DEFAULT_REHYPE_PLUGINS: MdxRollupPluginOptions['rehypePlugins'] = [];
 
 function handleExtends<T>(config: WithExtends<T[] | undefined>, defaults: T[] = []): T[] {
 	if (Array.isArray(config)) return config;
@@ -68,6 +71,8 @@ function getRehypePlugins(
 	if (config.markdown.syntaxHighlight === 'shiki' || config.markdown.syntaxHighlight === 'prism') {
 		rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
 	}
+	// getHeadings() is guaranteed by TS, so we can't allow user to override
+	rehypePlugins.push(rehypeCollectHeadings);
 
 	return rehypePlugins;
 }
diff --git a/packages/integrations/mdx/test/mdx-rehype-plugins.test.js b/packages/integrations/mdx/test/mdx-rehype-plugins.test.js
index d60c09a07..17430c750 100644
--- a/packages/integrations/mdx/test/mdx-rehype-plugins.test.js
+++ b/packages/integrations/mdx/test/mdx-rehype-plugins.test.js
@@ -34,17 +34,6 @@ describe('MDX rehype plugins', () => {
 			await fixture.build();
 		});
 
-		it('removes default getHeadings', async () => {
-			const html = await fixture.readFile('/space-ipsum/index.html');
-			const { document } = parseHTML(html);
-
-			const headings = [...document.querySelectorAll('h1, h2')];
-			expect(headings.length).to.be.greaterThan(0);
-			for (const heading of headings) {
-				expect(heading.id).to.be.empty;
-			}
-		});
-
 		it('supports custom rehype plugins - reading time', async () => {
 			const { readingTime } = JSON.parse(await fixture.readFile('/reading-time.json'));