From 18594c44ebbf168532a5bcb9745d568033a27d7d Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 20 Dec 2022 18:42:26 +0100 Subject: [PATCH 1/7] Refactor Markdown collect headings to store data in VFile --- packages/markdown/remark/src/index.ts | 13 ++- .../remark/src/rehype-collect-headings.ts | 106 +++++++++--------- packages/markdown/remark/src/types.ts | 6 + 3 files changed, 63 insertions(+), 62 deletions(-) diff --git a/packages/markdown/remark/src/index.ts b/packages/markdown/remark/src/index.ts index c64bdac0e0be..05361f9ff6c0 100644 --- a/packages/markdown/remark/src/index.ts +++ b/packages/markdown/remark/src/index.ts @@ -1,7 +1,7 @@ -import type { MarkdownRenderingOptions, MarkdownRenderingResult } from './types'; +import type { MarkdownRenderingOptions, MarkdownRenderingResult, MarkdownVFile } from './types'; import { loadPlugins } from './load-plugins.js'; -import createCollectHeadings from './rehype-collect-headings.js'; +import { rehypeHeadingSlugs } from './rehype-collect-headings.js'; import rehypeEscape from './rehype-escape.js'; import rehypeExpressions from './rehype-expressions.js'; import rehypeIslands from './rehype-islands.js'; @@ -22,6 +22,7 @@ import markdownToHtml from 'remark-rehype'; import { unified } from 'unified'; import { VFile } from 'vfile'; +export { rehypeHeadingSlugs } from './rehype-collect-headings.js'; export * from './types.js'; export const DEFAULT_REMARK_PLUGINS = ['remark-gfm', 'remark-smartypants']; @@ -44,7 +45,6 @@ export async function renderMarkdown( } = opts; const input = new VFile({ value: content, path: fileURL }); const scopedClassName = opts.$?.scopedClassName; - const { headings, rehypeCollectHeadings } = createCollectHeadings(); let parser = unified() .use(markdown) @@ -99,12 +99,12 @@ export async function renderMarkdown( parser .use( isAstroFlavoredMd - ? [rehypeJsx, rehypeExpressions, rehypeEscape, rehypeIslands, rehypeCollectHeadings] - : [rehypeCollectHeadings, rehypeRaw] + ? [rehypeJsx, rehypeExpressions, rehypeEscape, rehypeIslands, rehypeHeadingSlugs] + : [rehypeHeadingSlugs, rehypeRaw] ) .use(rehypeStringify, { allowDangerousHtml: true }); - let vfile: VFile; + let vfile: MarkdownVFile; try { vfile = await parser.process(input); } catch (err) { @@ -116,6 +116,7 @@ export async function renderMarkdown( throw err; } + const headings = vfile?.data.__astroHeadings || []; return { metadata: { headings, source: content, html: String(vfile.value) }, code: String(vfile.value), diff --git a/packages/markdown/remark/src/rehype-collect-headings.ts b/packages/markdown/remark/src/rehype-collect-headings.ts index b42ed9030558..034b0df36a7c 100644 --- a/packages/markdown/remark/src/rehype-collect-headings.ts +++ b/packages/markdown/remark/src/rehype-collect-headings.ts @@ -2,72 +2,66 @@ import Slugger from 'github-slugger'; import { toHtml } from 'hast-util-to-html'; import { visit } from 'unist-util-visit'; -import type { MarkdownHeading, RehypePlugin } from './types.js'; +import type { MarkdownHeading, MarkdownVFile, RehypePlugin } from './types.js'; -export default function createCollectHeadings() { - const headings: MarkdownHeading[] = []; - const slugger = new Slugger(); +export function rehypeHeadingSlugs(): ReturnType { + return function (tree, file: MarkdownVFile) { + const headings: MarkdownHeading[] = []; + const slugger = new Slugger(); + visit(tree, (node) => { + if (node.type !== 'element') return; + const { tagName } = node; + if (tagName[0] !== 'h') return; + const [_, level] = tagName.match(/h([0-6])/) ?? []; + if (!level) return; + const depth = Number.parseInt(level); - function rehypeCollectHeadings(): ReturnType { - return function (tree) { - visit(tree, (node) => { - if (node.type !== 'element') return; - const { tagName } = node; - if (tagName[0] !== 'h') return; - const [_, level] = tagName.match(/h([0-6])/) ?? []; - if (!level) return; - const depth = Number.parseInt(level); - - let text = ''; - let isJSX = false; - visit(node, (child, __, parent) => { - if (child.type === 'element' || parent == null) { + let text = ''; + let isJSX = false; + visit(node, (child, __, parent) => { + if (child.type === 'element' || parent == null) { + return; + } + if (child.type === 'raw') { + if (child.value.match(/^\n?<.*>\n?$/)) { return; } - if (child.type === 'raw') { - if (child.value.match(/^\n?<.*>\n?$/)) { - return; - } - } - if (child.type === 'text' || child.type === 'raw') { - if (new Set(['code', 'pre']).has(parent.tagName)) { - text += child.value; - } else { - text += child.value.replace(/\{/g, '${'); - isJSX = isJSX || child.value.includes('{'); - } + } + if (child.type === 'text' || child.type === 'raw') { + if (new Set(['code', 'pre']).has(parent.tagName)) { + text += child.value; + } else { + text += child.value.replace(/\{/g, '${'); + isJSX = isJSX || child.value.includes('{'); } - }); + } + }); - node.properties = node.properties || {}; - if (typeof node.properties.id !== 'string') { - if (isJSX) { - // HACK: serialized JSX from internal plugins, ignore these for slug - const raw = toHtml(node.children, { allowDangerousHtml: true }) - .replace(/\n(<)/g, '<') - .replace(/(>)\n/g, '>'); - // HACK: for ids that have JSX content, use $$slug helper to generate slug at runtime - node.properties.id = `$$slug(\`${text}\`)`; - (node as any).type = 'raw'; - ( - node as any - ).value = `<${node.tagName} id={${node.properties.id}}>${raw}`; - } else { - let slug = slugger.slug(text); + node.properties = node.properties || {}; + if (typeof node.properties.id !== 'string') { + if (isJSX) { + // HACK: serialized JSX from internal plugins, ignore these for slug + const raw = toHtml(node.children, { allowDangerousHtml: true }) + .replace(/\n(<)/g, '<') + .replace(/(>)\n/g, '>'); + // HACK: for ids that have JSX content, use $$slug helper to generate slug at runtime + node.properties.id = `$$slug(\`${text}\`)`; + (node as any).type = 'raw'; + ( + node as any + ).value = `<${node.tagName} id={${node.properties.id}}>${raw}`; + } else { + let slug = slugger.slug(text); - if (slug.endsWith('-')) slug = slug.slice(0, -1); + if (slug.endsWith('-')) slug = slug.slice(0, -1); - node.properties.id = slug; - } + node.properties.id = slug; } + } - headings.push({ depth, slug: node.properties.id, text }); - }); - }; - } + headings.push({ depth, slug: node.properties.id, text }); + }); - return { - headings, - rehypeCollectHeadings, + file.data.__astroHeadings = headings; }; } diff --git a/packages/markdown/remark/src/types.ts b/packages/markdown/remark/src/types.ts index 5b40c9f9d85f..76dfe9b73d98 100644 --- a/packages/markdown/remark/src/types.ts +++ b/packages/markdown/remark/src/types.ts @@ -68,6 +68,12 @@ export interface MarkdownMetadata { html: string; } +export interface MarkdownVFile extends VFile { + data: { + __astroHeadings?: MarkdownHeading[]; + }; +} + export interface MarkdownRenderingResult { metadata: MarkdownMetadata; vfile: VFile; From c0376b526001a08a89e60d0c1ed559026fc2176b Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 20 Dec 2022 19:13:49 +0100 Subject: [PATCH 2/7] Bring MDX support into core headings plugin --- .../markdown/remark/src/rehype-collect-headings.ts | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/packages/markdown/remark/src/rehype-collect-headings.ts b/packages/markdown/remark/src/rehype-collect-headings.ts index 034b0df36a7c..9cbaf76df157 100644 --- a/packages/markdown/remark/src/rehype-collect-headings.ts +++ b/packages/markdown/remark/src/rehype-collect-headings.ts @@ -4,10 +4,14 @@ import { visit } from 'unist-util-visit'; import type { MarkdownHeading, MarkdownVFile, RehypePlugin } from './types.js'; +const rawNodeTypes = new Set(['text', 'raw', 'mdxTextExpression']); +const codeTagNames = new Set(['code', 'pre']); + export function rehypeHeadingSlugs(): ReturnType { return function (tree, file: MarkdownVFile) { const headings: MarkdownHeading[] = []; const slugger = new Slugger(); + const isMDX = isMDXFile(file); visit(tree, (node) => { if (node.type !== 'element') return; const { tagName } = node; @@ -27,8 +31,8 @@ export function rehypeHeadingSlugs(): ReturnType { return; } } - if (child.type === 'text' || child.type === 'raw') { - if (new Set(['code', 'pre']).has(parent.tagName)) { + if (rawNodeTypes.has(child.type)) { + if (isMDX || codeTagNames.has(parent.tagName)) { text += child.value; } else { text += child.value.replace(/\{/g, '${'); @@ -65,3 +69,7 @@ export function rehypeHeadingSlugs(): ReturnType { file.data.__astroHeadings = headings; }; } + +function isMDXFile(file: MarkdownVFile) { + return file.history[0].endsWith('.mdx'); +} From c5441d4179c2a690445e0e0380ae1b9d3dfc1661 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 20 Dec 2022 19:26:19 +0100 Subject: [PATCH 3/7] Fix `isMDXFile` for vFiles with empty histories --- packages/markdown/remark/src/rehype-collect-headings.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/markdown/remark/src/rehype-collect-headings.ts b/packages/markdown/remark/src/rehype-collect-headings.ts index 9cbaf76df157..a23c408de6ca 100644 --- a/packages/markdown/remark/src/rehype-collect-headings.ts +++ b/packages/markdown/remark/src/rehype-collect-headings.ts @@ -71,5 +71,5 @@ export function rehypeHeadingSlugs(): ReturnType { } function isMDXFile(file: MarkdownVFile) { - return file.history[0].endsWith('.mdx'); + return Boolean(file.history[0]?.endsWith('.mdx')); } From 52ae39c925d1852409d048fba58017fcdd0e11f3 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 20 Dec 2022 19:31:26 +0100 Subject: [PATCH 4/7] Use `@astrojs/markdown-remark` heading slugger for MDX & run last --- packages/integrations/mdx/package.json | 1 + packages/integrations/mdx/src/plugins.ts | 14 ++++-- .../mdx/src/rehype-collect-headings.ts | 47 ++----------------- pnpm-lock.yaml | 2 + 4 files changed, 17 insertions(+), 47 deletions(-) diff --git a/packages/integrations/mdx/package.json b/packages/integrations/mdx/package.json index 01bbeb610c3b..08a681097437 100644 --- a/packages/integrations/mdx/package.json +++ b/packages/integrations/mdx/package.json @@ -30,6 +30,7 @@ "test:match": "mocha --timeout 20000 -g" }, "dependencies": { + "@astrojs/markdown-remark": "^1.1.3", "@astrojs/prism": "^1.0.2", "@mdx-js/mdx": "^2.1.2", "@mdx-js/rollup": "^2.1.1", diff --git a/packages/integrations/mdx/src/plugins.ts b/packages/integrations/mdx/src/plugins.ts index 0ae1487461ef..d0393b07a6a8 100644 --- a/packages/integrations/mdx/src/plugins.ts +++ b/packages/integrations/mdx/src/plugins.ts @@ -1,3 +1,4 @@ +import { rehypeHeadingSlugs } from '@astrojs/markdown-remark'; import { nodeTypes } from '@mdx-js/mdx'; import type { PluggableList } from '@mdx-js/mdx/lib/core.js'; import type { Options as MdxRollupPluginOptions } from '@mdx-js/rollup'; @@ -10,7 +11,7 @@ import remarkGfm from 'remark-gfm'; import remarkSmartypants from 'remark-smartypants'; import type { Data, VFile } from 'vfile'; import { MdxOptions } from './index.js'; -import rehypeCollectHeadings from './rehype-collect-headings.js'; +import { rehypeInjectHeadingsExport } from './rehype-collect-headings.js'; import rehypeMetaString from './rehype-meta-string.js'; import remarkPrism from './remark-prism.js'; import remarkShiki from './remark-shiki.js'; @@ -153,8 +154,6 @@ export function getRehypePlugins( config: AstroConfig ): MdxRollupPluginOptions['rehypePlugins'] { let rehypePlugins: PluggableList = [ - // getHeadings() is guaranteed by TS, so we can't allow user to override - rehypeCollectHeadings, // ensure `data.meta` is preserved in `properties.metastring` for rehype syntax highlighters rehypeMetaString, // rehypeRaw allows custom syntax highlighters to work without added config @@ -175,7 +174,14 @@ export function getRehypePlugins( break; } - rehypePlugins = [...rehypePlugins, ...(mdxOptions.rehypePlugins ?? [])]; + rehypePlugins = [ + ...rehypePlugins, + ...(mdxOptions.rehypePlugins ?? []), + // getHeadings() is guaranteed by TS, so this must be included. + // We run `rehypeHeadingSlugs` _last_ to respect any custom IDs set by user plugins. + rehypeHeadingSlugs, + rehypeInjectHeadingsExport, + ]; return rehypePlugins; } diff --git a/packages/integrations/mdx/src/rehype-collect-headings.ts b/packages/integrations/mdx/src/rehype-collect-headings.ts index 64bd7182b584..e6cd20a8d340 100644 --- a/packages/integrations/mdx/src/rehype-collect-headings.ts +++ b/packages/integrations/mdx/src/rehype-collect-headings.ts @@ -1,48 +1,9 @@ -import Slugger from 'github-slugger'; -import { visit } from 'unist-util-visit'; +import { MarkdownVFile, MarkdownHeading } from '@astrojs/markdown-remark'; import { jsToTreeNode } from './utils.js'; -export interface MarkdownHeading { - depth: number; - slug: string; - text: string; -} - -export default function rehypeCollectHeadings() { - const slugger = new Slugger(); - return function (tree: any) { - const headings: MarkdownHeading[] = []; - visit(tree, (node) => { - if (node.type !== 'element') return; - const { tagName } = node; - if (tagName[0] !== 'h') return; - const [_, level] = tagName.match(/h([0-6])/) ?? []; - if (!level) return; - const depth = Number.parseInt(level); - - let text = ''; - visit(node, (child, __, parent) => { - if (child.type === 'element' || parent == null) { - return; - } - if (child.type === 'raw' && child.value.match(/^\n?<.*>\n?$/)) { - return; - } - if (new Set(['text', 'raw', 'mdxTextExpression']).has(child.type)) { - text += child.value; - } - }); - - node.properties = node.properties || {}; - if (typeof node.properties.id !== 'string') { - let slug = slugger.slug(text); - if (slug.endsWith('-')) { - slug = slug.slice(0, -1); - } - node.properties.id = slug; - } - headings.push({ depth, slug: node.properties.id, text }); - }); +export function rehypeInjectHeadingsExport() { + return function (tree: any, file: MarkdownVFile) { + const headings: MarkdownHeading[] = file.data.__astroHeadings || []; tree.children.unshift( jsToTreeNode(`export function getHeadings() { return ${JSON.stringify(headings)} }`) ); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d391b5cf6d6b..cf302cdf7f14 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2880,6 +2880,7 @@ importers: packages/integrations/mdx: specifiers: + '@astrojs/markdown-remark': ^1.1.3 '@astrojs/prism': ^1.0.2 '@mdx-js/mdx': ^2.1.2 '@mdx-js/rollup': ^2.1.1 @@ -2916,6 +2917,7 @@ importers: vfile: ^5.3.2 vite: ^3.0.0 dependencies: + '@astrojs/markdown-remark': link:../../markdown/remark '@astrojs/prism': link:../../astro-prism '@mdx-js/mdx': 2.1.5 '@mdx-js/rollup': 2.1.5 From de825c95fd9758dfd2c1015b95033d9bc615ea10 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 20 Dec 2022 19:50:05 +0100 Subject: [PATCH 5/7] MDX tests: users can override IDs & inject IDs early with `rehypeHeadingSlugs` --- .../mdx/test/mdx-get-headings.test.js | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/packages/integrations/mdx/test/mdx-get-headings.test.js b/packages/integrations/mdx/test/mdx-get-headings.test.js index 1ac7283dd815..76fb60106c11 100644 --- a/packages/integrations/mdx/test/mdx-get-headings.test.js +++ b/packages/integrations/mdx/test/mdx-get-headings.test.js @@ -1,4 +1,6 @@ +import { rehypeHeadingSlugs } from '@astrojs/markdown-remark'; import mdx from '@astrojs/mdx'; +import { visit } from 'unist-util-visit'; import { expect } from 'chai'; import { parseHTML } from 'linkedom'; @@ -58,3 +60,92 @@ describe('MDX getHeadings', () => { ); }); }); + +describe('MDX heading IDs can be customized by user plugins', () => { + let fixture; + + before(async () => { + fixture = await loadFixture({ + root: new URL('./fixtures/mdx-get-headings/', import.meta.url), + integrations: [mdx()], + markdown: { + rehypePlugins: [ + () => (tree) => { + let count = 0; + visit(tree, 'element', (node, index, parent) => { + if (!/^h\d$/.test(node.tagName)) return; + if (!node.properties?.id) { + node.properties = { ...node.properties, id: String(count++) }; + } + }); + }, + ], + }, + }); + + await fixture.build(); + }); + + it('adds user-specified IDs to HTML output', async () => { + const html = await fixture.readFile('/test/index.html'); + const { document } = parseHTML(html); + + const h1 = document.querySelector('h1'); + expect(h1?.textContent).to.equal('Heading test'); + expect(h1?.getAttribute('id')).to.equal('0'); + + const headingIDs = document.querySelectorAll('h1,h2,h3').map((el) => el.id); + expect(JSON.stringify(headingIDs)).to.equal( + JSON.stringify(Array.from({ length: headingIDs.length }, (_, idx) => String(idx))) + ); + }); + + it('generates correct getHeadings() export', async () => { + const { headingsByPage } = JSON.parse(await fixture.readFile('/pages.json')); + expect(JSON.stringify(headingsByPage['./test.mdx'])).to.equal( + JSON.stringify([ + { depth: 1, slug: '0', text: 'Heading test' }, + { depth: 2, slug: '1', text: 'Section 1' }, + { depth: 3, slug: '2', text: 'Subsection 1' }, + { depth: 3, slug: '3', text: 'Subsection 2' }, + { depth: 2, slug: '4', text: 'Section 2' }, + ]) + ); + }); +}); + +describe('MDX heading IDs can be injected before user plugins', () => { + let fixture; + + before(async () => { + fixture = await loadFixture({ + root: new URL('./fixtures/mdx-get-headings/', import.meta.url), + integrations: [ + mdx({ + rehypePlugins: [ + rehypeHeadingSlugs, + () => (tree) => { + visit(tree, 'element', (node, index, parent) => { + if (!/^h\d$/.test(node.tagName)) return; + if (node.properties?.id) { + node.children.push({ type: 'text', value: ' ' + node.properties.id }); + } + }); + }, + ], + }), + ], + }); + + await fixture.build(); + }); + + it('adds user-specified IDs to HTML output', async () => { + const html = await fixture.readFile('/test/index.html'); + const { document } = parseHTML(html); + + const h1 = document.querySelector('h1'); + expect(h1?.textContent).to.equal('Heading test heading-test'); + expect(h1?.id).to.equal('heading-test'); + }); +}); From a579458bbef2f26cdcc0e2fd33c12a9dc9f742dd Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 20 Dec 2022 20:00:45 +0100 Subject: [PATCH 6/7] Add changesets --- .changeset/fast-baboons-prove.md | 27 +++++++++++++++++++++++++++ .changeset/violet-mice-push.md | 7 +++++++ 2 files changed, 34 insertions(+) create mode 100644 .changeset/fast-baboons-prove.md create mode 100644 .changeset/violet-mice-push.md diff --git a/.changeset/fast-baboons-prove.md b/.changeset/fast-baboons-prove.md new file mode 100644 index 000000000000..3ee00d4b1e9a --- /dev/null +++ b/.changeset/fast-baboons-prove.md @@ -0,0 +1,27 @@ +--- +'@astrojs/mdx': minor +--- + +Run heading ID injection after user plugins + +⚠️ BREAKING CHANGE ⚠️ + +If you are using a rehype plugin that depends on heading IDs injected by Astro, the IDs will no longer be available when your plugin runs by default. + +To inject IDs before your plugins run, import and add the `rehypeHeadingSlugs` plugin to your `rehypePlugins` config: + +```diff +// astro.config.mjs ++ import { rehypeHeadingSlugs } from '@astrojs/markdown-remark'; +import mdx from '@astrojs/mdx'; + +export default { + integrations: [mdx()], + markdown: { + rehypePlugins: [ ++ rehypeHeadingSlugs, + otherPluginThatReliesOnHeadingIDs, + ], + }, +} +``` diff --git a/.changeset/violet-mice-push.md b/.changeset/violet-mice-push.md new file mode 100644 index 000000000000..560f7a9bb7d1 --- /dev/null +++ b/.changeset/violet-mice-push.md @@ -0,0 +1,7 @@ +--- +'@astrojs/markdown-remark': minor +--- + +Refactor and export `rehypeHeadingSlugs` plugin + +The `rehypeHeadingSlugs` plugin injects IDs for all headings in a Markdown document and can now also handle MDX inputs if needed. You can import and use this plugin if you need heading IDs to be injected _before_ other rehype plugins run. From 13d0c0bd6daf7610d7fcb67e8cd0ae2995444066 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 20 Dec 2022 21:54:27 +0100 Subject: [PATCH 7/7] Rename plugin to `rehypeHeadingIds` as per @bholmesdev suggestion --- .changeset/fast-baboons-prove.md | 6 +++--- .changeset/violet-mice-push.md | 4 ++-- packages/integrations/mdx/src/plugins.ts | 6 +++--- packages/integrations/mdx/test/mdx-get-headings.test.js | 4 ++-- packages/markdown/remark/src/index.ts | 8 ++++---- packages/markdown/remark/src/rehype-collect-headings.ts | 2 +- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/.changeset/fast-baboons-prove.md b/.changeset/fast-baboons-prove.md index 3ee00d4b1e9a..42cd710b2743 100644 --- a/.changeset/fast-baboons-prove.md +++ b/.changeset/fast-baboons-prove.md @@ -8,18 +8,18 @@ Run heading ID injection after user plugins If you are using a rehype plugin that depends on heading IDs injected by Astro, the IDs will no longer be available when your plugin runs by default. -To inject IDs before your plugins run, import and add the `rehypeHeadingSlugs` plugin to your `rehypePlugins` config: +To inject IDs before your plugins run, import and add the `rehypeHeadingIds` plugin to your `rehypePlugins` config: ```diff // astro.config.mjs -+ import { rehypeHeadingSlugs } from '@astrojs/markdown-remark'; ++ import { rehypeHeadingIds } from '@astrojs/markdown-remark'; import mdx from '@astrojs/mdx'; export default { integrations: [mdx()], markdown: { rehypePlugins: [ -+ rehypeHeadingSlugs, ++ rehypeHeadingIds, otherPluginThatReliesOnHeadingIDs, ], }, diff --git a/.changeset/violet-mice-push.md b/.changeset/violet-mice-push.md index 560f7a9bb7d1..8b111f6c7d78 100644 --- a/.changeset/violet-mice-push.md +++ b/.changeset/violet-mice-push.md @@ -2,6 +2,6 @@ '@astrojs/markdown-remark': minor --- -Refactor and export `rehypeHeadingSlugs` plugin +Refactor and export `rehypeHeadingIds` plugin -The `rehypeHeadingSlugs` plugin injects IDs for all headings in a Markdown document and can now also handle MDX inputs if needed. You can import and use this plugin if you need heading IDs to be injected _before_ other rehype plugins run. +The `rehypeHeadingIds` plugin injects IDs for all headings in a Markdown document and can now also handle MDX inputs if needed. You can import and use this plugin if you need heading IDs to be injected _before_ other rehype plugins run. diff --git a/packages/integrations/mdx/src/plugins.ts b/packages/integrations/mdx/src/plugins.ts index d0393b07a6a8..d46ab6cd418f 100644 --- a/packages/integrations/mdx/src/plugins.ts +++ b/packages/integrations/mdx/src/plugins.ts @@ -1,4 +1,4 @@ -import { rehypeHeadingSlugs } from '@astrojs/markdown-remark'; +import { rehypeHeadingIds } from '@astrojs/markdown-remark'; import { nodeTypes } from '@mdx-js/mdx'; import type { PluggableList } from '@mdx-js/mdx/lib/core.js'; import type { Options as MdxRollupPluginOptions } from '@mdx-js/rollup'; @@ -178,8 +178,8 @@ export function getRehypePlugins( ...rehypePlugins, ...(mdxOptions.rehypePlugins ?? []), // getHeadings() is guaranteed by TS, so this must be included. - // We run `rehypeHeadingSlugs` _last_ to respect any custom IDs set by user plugins. - rehypeHeadingSlugs, + // We run `rehypeHeadingIds` _last_ to respect any custom IDs set by user plugins. + rehypeHeadingIds, rehypeInjectHeadingsExport, ]; return rehypePlugins; diff --git a/packages/integrations/mdx/test/mdx-get-headings.test.js b/packages/integrations/mdx/test/mdx-get-headings.test.js index 76fb60106c11..03290abc5b67 100644 --- a/packages/integrations/mdx/test/mdx-get-headings.test.js +++ b/packages/integrations/mdx/test/mdx-get-headings.test.js @@ -1,4 +1,4 @@ -import { rehypeHeadingSlugs } from '@astrojs/markdown-remark'; +import { rehypeHeadingIds } from '@astrojs/markdown-remark'; import mdx from '@astrojs/mdx'; import { visit } from 'unist-util-visit'; @@ -123,7 +123,7 @@ describe('MDX heading IDs can be injected before user plugins', () => { integrations: [ mdx({ rehypePlugins: [ - rehypeHeadingSlugs, + rehypeHeadingIds, () => (tree) => { visit(tree, 'element', (node, index, parent) => { if (!/^h\d$/.test(node.tagName)) return; diff --git a/packages/markdown/remark/src/index.ts b/packages/markdown/remark/src/index.ts index 05361f9ff6c0..6d69bcd20a20 100644 --- a/packages/markdown/remark/src/index.ts +++ b/packages/markdown/remark/src/index.ts @@ -1,7 +1,7 @@ import type { MarkdownRenderingOptions, MarkdownRenderingResult, MarkdownVFile } from './types'; import { loadPlugins } from './load-plugins.js'; -import { rehypeHeadingSlugs } from './rehype-collect-headings.js'; +import { rehypeHeadingIds } from './rehype-collect-headings.js'; import rehypeEscape from './rehype-escape.js'; import rehypeExpressions from './rehype-expressions.js'; import rehypeIslands from './rehype-islands.js'; @@ -22,7 +22,7 @@ import markdownToHtml from 'remark-rehype'; import { unified } from 'unified'; import { VFile } from 'vfile'; -export { rehypeHeadingSlugs } from './rehype-collect-headings.js'; +export { rehypeHeadingIds } from './rehype-collect-headings.js'; export * from './types.js'; export const DEFAULT_REMARK_PLUGINS = ['remark-gfm', 'remark-smartypants']; @@ -99,8 +99,8 @@ export async function renderMarkdown( parser .use( isAstroFlavoredMd - ? [rehypeJsx, rehypeExpressions, rehypeEscape, rehypeIslands, rehypeHeadingSlugs] - : [rehypeHeadingSlugs, rehypeRaw] + ? [rehypeJsx, rehypeExpressions, rehypeEscape, rehypeIslands, rehypeHeadingIds] + : [rehypeHeadingIds, rehypeRaw] ) .use(rehypeStringify, { allowDangerousHtml: true }); diff --git a/packages/markdown/remark/src/rehype-collect-headings.ts b/packages/markdown/remark/src/rehype-collect-headings.ts index a23c408de6ca..03a3c6a23eae 100644 --- a/packages/markdown/remark/src/rehype-collect-headings.ts +++ b/packages/markdown/remark/src/rehype-collect-headings.ts @@ -7,7 +7,7 @@ import type { MarkdownHeading, MarkdownVFile, RehypePlugin } from './types.js'; const rawNodeTypes = new Set(['text', 'raw', 'mdxTextExpression']); const codeTagNames = new Set(['code', 'pre']); -export function rehypeHeadingSlugs(): ReturnType { +export function rehypeHeadingIds(): ReturnType { return function (tree, file: MarkdownVFile) { const headings: MarkdownHeading[] = []; const slugger = new Slugger();