@astrojs/mdx 0.13.0 → 0.14.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
-@astrojs/mdx:build: cache hit, replaying output 72ab36e70338807d
-@astrojs/mdx:build: 
-@astrojs/mdx:build: > @astrojs/mdx@0.13.0 build /home/runner/work/astro/astro/packages/integrations/mdx
-@astrojs/mdx:build: > astro-scripts build "src/**/*.ts" && tsc
-@astrojs/mdx:build: 
+@astrojs/mdx:build: cache hit, replaying output 93db87e92a57f3ab
+@astrojs/mdx:build: 
+@astrojs/mdx:build: > @astrojs/mdx@0.14.0 build /home/runner/work/astro/astro/packages/integrations/mdx
+@astrojs/mdx:build: > astro-scripts build "src/**/*.ts" && tsc
+@astrojs/mdx:build: 

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @astrojs/mdx
 
+## 0.14.0
+
+### Minor Changes
+
+- [#5654](https://github.com/withastro/astro/pull/5654) [`2c65b433b`](https://github.com/withastro/astro/commit/2c65b433bf840a1bb93b0a1947df5949e33512ff) Thanks [@delucis](https://github.com/delucis)! - 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 `rehypeHeadingIds` plugin to your `rehypePlugins` config:
+
+  ```diff
+  // astro.config.mjs
+  + import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+  import mdx from '@astrojs/mdx';
+
+  export default {
+    integrations: [mdx()],
+    markdown: {
+      rehypePlugins: [
+  +     rehypeHeadingIds,
+        otherPluginThatReliesOnHeadingIDs,
+      ],
+    },
+  }
+  ```
+
+### Patch Changes
+
+- [#5667](https://github.com/withastro/astro/pull/5667) [`a5ba4af79`](https://github.com/withastro/astro/commit/a5ba4af79930145f4edf66d45cd40ddad045cc86) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Chore: remove verbose "Now interiting Markdown plugins..." logs
+
+- [#5648](https://github.com/withastro/astro/pull/5648) [`853081d1c`](https://github.com/withastro/astro/commit/853081d1c857d8ad8a9634c37ed8fd123d32d241) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Prevent relative image paths in `src/content/`
+
+- Updated dependencies [[`853081d1c`](https://github.com/withastro/astro/commit/853081d1c857d8ad8a9634c37ed8fd123d32d241), [`2c65b433b`](https://github.com/withastro/astro/commit/2c65b433bf840a1bb93b0a1947df5949e33512ff)]:
+  - @astrojs/markdown-remark@1.2.0
+
 ## 0.13.0
 
 ### Minor Changes

package/dist/index.js

@@ -1,7 +1,6 @@
 import { compile as mdxCompile } from "@mdx-js/mdx";
 import mdxPlugin from "@mdx-js/rollup";
 import { parse as parseESM } from "es-module-lexer";
-import { blue, bold } from "kleur/colors";
 import fs from "node:fs/promises";
 import { VFile } from "vfile";
 import {
@@ -10,7 +9,7 @@ import {
   recmaInjectImportMetaEnvPlugin,
   rehypeApplyFrontmatterExport
 } from "./plugins.js";
-import { getFileInfo, handleExtendsNotSupported, parseFrontmatter } from "./utils.js";
+import { getFileInfo, parseFrontmatter } from "./utils.js";
 const RAW_CONTENT_ERROR = "MDX does not support rawContent()! If you need to read the Markdown contents to calculate values (ex. reading time), we suggest injecting frontmatter via remark plugins. Learn more on our docs: https://docs.astro.build/en/guides/integrations-guide/mdx/#inject-frontmatter-via-remark-or-rehype-plugins";
 const COMPILED_CONTENT_ERROR = "MDX does not support compiledContent()! If you need to read the HTML contents to calculate values (ex. reading time), we suggest injecting frontmatter via rehype plugins. Learn more on our docs: https://docs.astro.build/en/guides/integrations-guide/mdx/#inject-frontmatter-via-remark-or-rehype-plugins";
 function mdx(mdxOptions = {}) {
@@ -18,29 +17,12 @@ function mdx(mdxOptions = {}) {
     name: "@astrojs/mdx",
     hooks: {
       "astro:config:setup": async ({ updateConfig, config, addPageExtension, command }) => {
-        var _a, _b;
         addPageExtension(".mdx");
         mdxOptions.extendPlugins ?? (mdxOptions.extendPlugins = "markdown");
-        handleExtendsNotSupported(mdxOptions.remarkPlugins);
-        handleExtendsNotSupported(mdxOptions.rehypePlugins);
-        if (mdxOptions.extendPlugins === "markdown" && (((_a = config.markdown.rehypePlugins) == null ? void 0 : _a.length) || ((_b = config.markdown.remarkPlugins) == null ? void 0 : _b.length))) {
-          console.info(
-            blue(`[MDX] Now inheriting remark and rehype plugins from "markdown" config.`)
-          );
-          console.info(
-            `If you applied a plugin to both your Markdown and MDX configs, we suggest ${bold(
-              "removing the duplicate MDX entry."
-            )}`
-          );
-          console.info(`See "extendPlugins" option to configure this behavior.`);
-        }
-        let remarkRehypeOptions = mdxOptions.remarkRehype;
-        if (mdxOptions.extendPlugins === "markdown") {
-          remarkRehypeOptions = {
-            ...config.markdown.remarkRehype,
-            ...remarkRehypeOptions
-          };
-        }
+        const remarkRehypeOptions = {
+          ...mdxOptions.extendPlugins === "markdown" ? config.markdown.remarkRehype : {},
+          ...mdxOptions.remarkRehype
+        };
         const mdxPluginOpts = {
           remarkPlugins: await getRemarkPlugins(mdxOptions, config),
           rehypePlugins: getRehypePlugins(mdxOptions, config),

package/dist/plugins.js

@@ -1,14 +1,17 @@
+import { rehypeHeadingIds } from "@astrojs/markdown-remark";
 import { nodeTypes } from "@mdx-js/mdx";
 import { visit as estreeVisit } from "estree-util-visit";
 import { bold, yellow } from "kleur/colors";
+import { pathToFileURL } from "node:url";
 import rehypeRaw from "rehype-raw";
 import remarkGfm from "remark-gfm";
 import remarkSmartypants from "remark-smartypants";
-import rehypeCollectHeadings from "./rehype-collect-headings.js";
+import { visit } from "unist-util-visit";
+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";
-import { jsToTreeNode } from "./utils.js";
+import { isRelativePath, jsToTreeNode } from "./utils.js";
 function recmaInjectImportMetaEnvPlugin({
   importMetaEnv
 }) {
@@ -94,6 +97,27 @@ export const _internal = { injectedFrontmatter: ${JSON.stringify(
     tree.children = exportNodes.concat(tree.children);
   };
 }
+function toRemarkContentRelImageError({ srcDir }) {
+  const contentDir = new URL("content/", srcDir);
+  return function remarkContentRelImageError() {
+    return (tree, vfile) => {
+      const isContentFile = pathToFileURL(vfile.path).href.startsWith(contentDir.href);
+      if (!isContentFile)
+        return;
+      const relImagePaths = /* @__PURE__ */ new Set();
+      visit(tree, "image", function raiseError(node) {
+        if (isRelativePath(node.url)) {
+          relImagePaths.add(node.url);
+        }
+      });
+      if (relImagePaths.size === 0)
+        return;
+      const errorMessage = `Relative image paths are not supported in the content/ directory. Place local images in the public/ directory and use absolute paths (see https://docs.astro.build/en/guides/images/#in-markdown-files):
+` + [...relImagePaths].map((path) => JSON.stringify(path)).join(",\n");
+      throw new Error(errorMessage);
+    };
+  };
+}
 const DEFAULT_REMARK_PLUGINS = [remarkGfm, remarkSmartypants];
 const DEFAULT_REHYPE_PLUGINS = [];
 async function getRemarkPlugins(mdxOptions, config) {
@@ -121,11 +145,13 @@ async function getRemarkPlugins(mdxOptions, config) {
     remarkPlugins.push(remarkPrism);
   }
   remarkPlugins = [...remarkPlugins, ...mdxOptions.remarkPlugins ?? []];
+  if (config.experimental.contentCollections) {
+    remarkPlugins.push(toRemarkContentRelImageError(config));
+  }
   return remarkPlugins;
 }
 function getRehypePlugins(mdxOptions, config) {
   let rehypePlugins = [
-    rehypeCollectHeadings,
     rehypeMetaString,
     [rehypeRaw, { passThrough: nodeTypes }]
   ];
@@ -143,7 +169,12 @@ function getRehypePlugins(mdxOptions, config) {
       ];
       break;
   }
-  rehypePlugins = [...rehypePlugins, ...mdxOptions.rehypePlugins ?? []];
+  rehypePlugins = [
+    ...rehypePlugins,
+    ...mdxOptions.rehypePlugins ?? [],
+    rehypeHeadingIds,
+    rehypeInjectHeadingsExport
+  ];
   return rehypePlugins;
 }
 function markdownShouldExtendDefaultPlugins(config) {

package/dist/rehype-collect-headings.d.ts

@@ -1,6 +1,2 @@
-export interface MarkdownHeading {
-    depth: number;
-    slug: string;
-    text: string;
-}
-export default function rehypeCollectHeadings(): (tree: any) => void;
+import { MarkdownVFile } from '@astrojs/markdown-remark';
+export declare function rehypeInjectHeadingsExport(): (tree: any, file: MarkdownVFile) => void;

package/dist/rehype-collect-headings.js

@@ -1,47 +1,12 @@
-import Slugger from "github-slugger";
-import { visit } from "unist-util-visit";
 import { jsToTreeNode } from "./utils.js";
-function rehypeCollectHeadings() {
-  const slugger = new Slugger();
-  return function(tree) {
-    const headings = [];
-    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 ((/* @__PURE__ */ 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 });
-    });
+function rehypeInjectHeadingsExport() {
+  return function(tree, file) {
+    const headings = file.data.__astroHeadings || [];
     tree.children.unshift(
       jsToTreeNode(`export function getHeadings() { return ${JSON.stringify(headings)} }`)
     );
   };
 }
 export {
-  rehypeCollectHeadings as default
+  rehypeInjectHeadingsExport
 };

package/dist/utils.d.ts

@@ -14,5 +14,5 @@ export declare function getFileInfo(id: string, config: AstroConfig): FileInfo;
  */
 export declare function parseFrontmatter(code: string, id: string): matter.GrayMatterFile<string>;
 export declare function jsToTreeNode(jsString: string, acornOpts?: AcornOpts): MdxjsEsm;
-export declare function handleExtendsNotSupported(pluginConfig: any): void;
+export declare function isRelativePath(path: string): boolean;
 export {};

package/dist/utils.js

@@ -59,16 +59,23 @@ function jsToTreeNode(jsString, acornOpts = {
     }
   };
 }
-function handleExtendsNotSupported(pluginConfig) {
-  if (typeof pluginConfig === "object" && pluginConfig !== null && pluginConfig.hasOwnProperty("extends")) {
-    throw new Error(
-      `[MDX] The "extends" plugin option is no longer supported! Astro now extends your project's \`markdown\` plugin configuration by default. To customize this behavior, see the \`extendPlugins\` option instead: https://docs.astro.build/en/guides/integrations-guide/mdx/#extendplugins`
-    );
-  }
+function isRelativePath(path) {
+  return startsWithDotDotSlash(path) || startsWithDotSlash(path);
+}
+function startsWithDotDotSlash(path) {
+  const c1 = path[0];
+  const c2 = path[1];
+  const c3 = path[2];
+  return c1 === "." && c2 === "." && c3 === "/";
+}
+function startsWithDotSlash(path) {
+  const c1 = path[0];
+  const c2 = path[1];
+  return c1 === "." && c2 === "/";
 }
 export {
   getFileInfo,
-  handleExtendsNotSupported,
+  isRelativePath,
   jsToTreeNode,
   parseFrontmatter
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/mdx",
   "description": "Use MDX within Astro",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -23,6 +23,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@astrojs/markdown-remark": "^1.2.0",
     "@astrojs/prism": "^1.0.2",
     "@mdx-js/mdx": "^2.1.2",
     "@mdx-js/rollup": "^2.1.1",
@@ -44,9 +45,10 @@
     "@types/chai": "^4.3.1",
     "@types/estree": "^1.0.0",
     "@types/github-slugger": "^1.3.0",
+    "@types/mdast": "^3.0.10",
     "@types/mocha": "^9.1.1",
     "@types/yargs-parser": "^21.0.0",
-    "astro": "1.7.0",
+    "astro": "1.8.0",
     "astro-scripts": "0.0.9",
     "chai": "^4.3.6",
     "cheerio": "^1.0.0-rc.11",

package/src/index.ts

@@ -3,7 +3,6 @@ import { PluggableList } from '@mdx-js/mdx/lib/core.js';
 import mdxPlugin, { Options as MdxRollupPluginOptions } from '@mdx-js/rollup';
 import type { AstroIntegration } from 'astro';
 import { parse as parseESM } from 'es-module-lexer';
-import { blue, bold } from 'kleur/colors';
 import fs from 'node:fs/promises';
 import type { Options as RemarkRehypeOptions } from 'remark-rehype';
 import { VFile } from 'vfile';
@@ -14,7 +13,7 @@ import {
 	recmaInjectImportMetaEnvPlugin,
 	rehypeApplyFrontmatterExport,
 } from './plugins.js';
-import { getFileInfo, handleExtendsNotSupported, parseFrontmatter } from './utils.js';
+import { getFileInfo, parseFrontmatter } from './utils.js';
 
 const RAW_CONTENT_ERROR =
 	'MDX does not support rawContent()! If you need to read the Markdown contents to calculate values (ex. reading time), we suggest injecting frontmatter via remark plugins. Learn more on our docs: https://docs.astro.build/en/guides/integrations-guide/mdx/#inject-frontmatter-via-remark-or-rehype-plugins';
@@ -45,33 +44,10 @@ export default function mdx(mdxOptions: MdxOptions = {}): AstroIntegration {
 				addPageExtension('.mdx');
 				mdxOptions.extendPlugins ??= 'markdown';
 
-				handleExtendsNotSupported(mdxOptions.remarkPlugins);
-				handleExtendsNotSupported(mdxOptions.rehypePlugins);
-
-				// TODO: remove for 1.0. Shipping to ease migration to new minor
-				if (
-					mdxOptions.extendPlugins === 'markdown' &&
-					(config.markdown.rehypePlugins?.length || config.markdown.remarkPlugins?.length)
-				) {
-					console.info(
-						blue(`[MDX] Now inheriting remark and rehype plugins from "markdown" config.`)
-					);
-					console.info(
-						`If you applied a plugin to both your Markdown and MDX configs, we suggest ${bold(
-							'removing the duplicate MDX entry.'
-						)}`
-					);
-					console.info(`See "extendPlugins" option to configure this behavior.`);
-				}
-
-				let remarkRehypeOptions = mdxOptions.remarkRehype;
-
-				if (mdxOptions.extendPlugins === 'markdown') {
-					remarkRehypeOptions = {
-						...config.markdown.remarkRehype,
-						...remarkRehypeOptions,
-					};
-				}
+				const remarkRehypeOptions = {
+					...(mdxOptions.extendPlugins === 'markdown' ? config.markdown.remarkRehype : {}),
+					...mdxOptions.remarkRehype,
+				};
 
 				const mdxPluginOpts: MdxRollupPluginOptions = {
 					remarkPlugins: await getRemarkPlugins(mdxOptions, config),

package/src/plugins.ts

@@ -1,3 +1,4 @@
+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';
@@ -5,16 +6,19 @@ import type { AstroConfig, MarkdownAstroData } from 'astro';
 import type { Literal, MemberExpression } from 'estree';
 import { visit as estreeVisit } from 'estree-util-visit';
 import { bold, yellow } from 'kleur/colors';
+import type { Image } from 'mdast';
+import { pathToFileURL } from 'node:url';
 import rehypeRaw from 'rehype-raw';
 import remarkGfm from 'remark-gfm';
 import remarkSmartypants from 'remark-smartypants';
+import { visit } from 'unist-util-visit';
 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';
-import { jsToTreeNode } from './utils.js';
+import { isRelativePath, jsToTreeNode } from './utils.js';
 
 export function recmaInjectImportMetaEnvPlugin({
 	importMetaEnv,
@@ -112,6 +116,34 @@ export function rehypeApplyFrontmatterExport(pageFrontmatter: Record<string, any
 	};
 }
 
+/**
+ * `src/content/` does not support relative image paths.
+ * This plugin throws an error if any are found
+ */
+function toRemarkContentRelImageError({ srcDir }: { srcDir: URL }) {
+	const contentDir = new URL('content/', srcDir);
+	return function remarkContentRelImageError() {
+		return (tree: any, vfile: VFile) => {
+			const isContentFile = pathToFileURL(vfile.path).href.startsWith(contentDir.href);
+			if (!isContentFile) return;
+
+			const relImagePaths = new Set<string>();
+			visit(tree, 'image', function raiseError(node: Image) {
+				if (isRelativePath(node.url)) {
+					relImagePaths.add(node.url);
+				}
+			});
+			if (relImagePaths.size === 0) return;
+
+			const errorMessage =
+				`Relative image paths are not supported in the content/ directory. Place local images in the public/ directory and use absolute paths (see https://docs.astro.build/en/guides/images/#in-markdown-files):\n` +
+				[...relImagePaths].map((path) => JSON.stringify(path)).join(',\n');
+
+			throw new Error(errorMessage);
+		};
+	};
+}
+
 const DEFAULT_REMARK_PLUGINS: PluggableList = [remarkGfm, remarkSmartypants];
 const DEFAULT_REHYPE_PLUGINS: PluggableList = [];
 
@@ -145,6 +177,11 @@ export async function getRemarkPlugins(
 	}
 
 	remarkPlugins = [...remarkPlugins, ...(mdxOptions.remarkPlugins ?? [])];
+
+	// Apply last in case user plugins resolve relative image paths
+	if (config.experimental.contentCollections) {
+		remarkPlugins.push(toRemarkContentRelImageError(config));
+	}
 	return remarkPlugins;
 }
 
@@ -153,8 +190,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 +210,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 `rehypeHeadingIds` _last_ to respect any custom IDs set by user plugins.
+		rehypeHeadingIds,
+		rehypeInjectHeadingsExport,
+	];
 	return rehypePlugins;
 }
 

package/src/rehype-collect-headings.ts

@@ -1,48 +1,9 @@
-import Slugger from 'github-slugger';
-import { visit } from 'unist-util-visit';
+import { MarkdownHeading, MarkdownVFile } 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)} }`)
 		);

package/src/utils.ts

@@ -83,15 +83,20 @@ export function jsToTreeNode(
 	};
 }
 
-// TODO: remove for 1.0
-export function handleExtendsNotSupported(pluginConfig: any) {
-	if (
-		typeof pluginConfig === 'object' &&
-		pluginConfig !== null &&
-		(pluginConfig as any).hasOwnProperty('extends')
-	) {
-		throw new Error(
-			`[MDX] The "extends" plugin option is no longer supported! Astro now extends your project's \`markdown\` plugin configuration by default. To customize this behavior, see the \`extendPlugins\` option instead: https://docs.astro.build/en/guides/integrations-guide/mdx/#extendplugins`
-		);
-	}
+// Following utils taken from `packages/astro/src/core/path.ts`:
+export function isRelativePath(path: string) {
+	return startsWithDotDotSlash(path) || startsWithDotSlash(path);
+}
+
+function startsWithDotDotSlash(path: string) {
+	const c1 = path[0];
+	const c2 = path[1];
+	const c3 = path[2];
+	return c1 === '.' && c2 === '.' && c3 === '/';
+}
+
+function startsWithDotSlash(path: string) {
+	const c1 = path[0];
+	const c2 = path[1];
+	return c1 === '.' && c2 === '/';
 }

package/test/mdx-get-headings.test.js

@@ -1,4 +1,6 @@
+import { rehypeHeadingIds } 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: [
+						rehypeHeadingIds,
+						() => (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');
+	});
+});