michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
* 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
This commit is contained in:
Ben Holmes 2022-08-05 22:51:38 -05:00 committed by GitHub
parent 97cf0cd893
commit 77cede720b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 14 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.changeset/afraid-rules-boil.md Normal file
View file

@ -0,0 +1,5 @@
---
'@astrojs/mdx': patch
---
Make collect-headings rehype plugin non-overridable

19
packages/integrations/mdx/README.md
View file

@ -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).
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).
To apply rehype plugins _while preserving_ Astro's default plugins, use a nested `extends` object like so:
```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

9
packages/integrations/mdx/src/index.ts
View file

@ -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;
}

11
packages/integrations/mdx/test/mdx-rehype-plugins.test.js
View file

@ -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'));