feat(mdx): Rust MDX via satteri

Author: Princesseuh

.changeset/seven-emus-knock.md

@@ -0,0 +1,7 @@
+---
+'astro': patch
+'@astrojs/markdown-remark': patch
+'@astrojs/mdx': patch
+---
+
+temp changeset for preview release

knip.js

@@ -83,6 +83,12 @@ export default {
 			entry: [srcEntry, dtsEntry, testEntry],
 			// package.json#imports are not resolved at the moment
 			ignore: ['src/import-plugin-browser.ts', 'src/shiki-engine-workerd.ts'],
+			ignoreDependencies: [
+				// Optional peer dep loaded dynamically by createSatteriMarkdownProcessor
+				'satteri',
+				// Pulled in indirectly through satteri's browser WASM shim during bundler tests
+				'@napi-rs/wasm-runtime',
+			],
 		},
 		'packages/upgrade': {
 			entry: ['src/index.ts', testEntry],

packages/astro/package.json

@@ -196,6 +196,7 @@
   },
   "devDependencies": {
     "@astrojs/check": "workspace:*",
+    "satteri": "^0.2.7",
     "@playwright/test": "1.58.2",
     "@types/aria-query": "^5.0.4",
     "@types/hast": "^3.0.4",

packages/astro/src/core/config/schemas/base.ts

@@ -111,6 +111,7 @@ export const ASTRO_CONFIG_DEFAULTS = {
 		clientPrerender: false,
 		contentIntellisense: false,
 		chromeDevtoolsWorkspace: false,
+		nativeMarkdown: false,
 		queuedRendering: {
 			enabled: false,
 		},
@@ -550,6 +551,23 @@ export const AstroConfigSchema = z.object({
 			svgOptimizer: SvgOptimizerSchema.optional(),
 			cache: CacheSchema.optional(),
 			routeRules: RouteRulesSchema.optional(),
+			nativeMarkdown: z
+				.union([
+					z.boolean(),
+					z.object({
+						mdastPlugins: z
+							.array(z.custom<import('satteri').MdastPluginDefinition>())
+							.optional()
+							.default([]),
+						hastPlugins: z
+							.array(z.custom<import('satteri').HastPluginDefinition>())
+							.optional()
+							.default([]),
+						features: z.custom<import('satteri').Features>().optional(),
+					}),
+				])
+				.optional()
+				.default(ASTRO_CONFIG_DEFAULTS.experimental.nativeMarkdown),
 			queuedRendering: z
 				.object({
 					enabled: z.boolean().optional().prefault(false),

packages/astro/src/jsx/rehype.ts

@@ -24,8 +24,13 @@ export const rehypeAnalyzeAstroMetadata: RehypePlugin = () => {
 		// Parse imports in this file. This is used to match components with their import source
 		const imports = parseImports(tree.children);
 
-		visit(tree, (node) => {
-			if (node.type !== 'mdxJsxFlowElement' && node.type !== 'mdxJsxTextElement') return;
+		visit(tree, (visitedNode) => {
+			if (visitedNode.type !== 'mdxJsxFlowElement' && visitedNode.type !== 'mdxJsxTextElement')
+				return;
+
+			// `visit` returns nodes typed against widened hast augmentations (e.g. from satteri).
+			// Narrow back to the mdast-util-mdx-jsx types our helpers expect.
+			const node = visitedNode as unknown as MdxJsxFlowElementHast | MdxJsxTextElementHast;
 
 			const tagName = node.name;
 			if (
@@ -106,6 +111,27 @@ export function getAstroMetadata(file: VFile) {
 
 type ImportSpecifier = { local: string; imported: string };
 
+// Minimal ESTree shapes we need — avoids a direct dependency on @types/estree.
+// `@types/estree` is present transitively but not in our direct deps, and satteri's
+// hast augmentations widen `mdxjsEsm.data.estree` to `{}`, erasing its Program typing.
+type EstreeId = { type: 'Identifier'; name: string };
+type EstreeLiteral = { type: 'Literal'; value: unknown };
+type EstreeImportSpecifier =
+	| { type: 'ImportDefaultSpecifier'; local: EstreeId }
+	| { type: 'ImportNamespaceSpecifier'; local: EstreeId }
+	| {
+			type: 'ImportSpecifier';
+			local: EstreeId;
+			imported: EstreeId | EstreeLiteral;
+	  };
+type EstreeImportDeclaration = {
+	type: 'ImportDeclaration';
+	source: { value: string };
+	specifiers: EstreeImportSpecifier[];
+};
+type EstreeStatement = EstreeImportDeclaration | { type: 'OtherStatement' };
+type EstreeProgram = { body: EstreeStatement[] };
+
 /**
  * ```
  * import Foo from './Foo.jsx'
@@ -130,7 +156,9 @@ function parseImports(children: RootContent[]) {
 	for (const child of children) {
 		if (child.type !== 'mdxjsEsm') continue;
 
-		const body = child.data?.estree?.body;
+		// `child.data?.estree` is widened by the hast augmentations; narrow it back to the shape
+		// we care about (an ESTree Program with ImportDeclaration bodies).
+		const body = (child.data?.estree as EstreeProgram | undefined)?.body;
 		if (!body) continue;
 
 		for (const ast of body) {

packages/astro/src/types/public/config.ts

@@ -2997,6 +2997,56 @@ export interface AstroUserConfig<
 		 */
 		routeRules?: RouteRules;
 
+		/**
+		 * @name experimental.nativeMarkdown
+		 * @type {boolean | { mdastPlugins?: import('satteri').MdastPluginDefinition[]; hastPlugins?: import('satteri').HastPluginDefinition[]; features?: import('satteri').Features }}
+		 * @default `false`
+		 * @version 6.0.0
+		 * @description
+		 *
+		 * Enables the experimental native Markdown compiler (satteri) as a replacement for the default remark/rehype pipeline.
+		 * When enabled, both Markdown and MDX files are processed using satteri, a Rust-based compiler that offers improved performance.
+		 *
+		 * This option requires installing the `satteri` package manually in your project.
+		 * When enabled, `remarkPlugins` and `rehypePlugins` from the markdown config are ignored.
+		 * Use `mdastPlugins` and `hastPlugins` (satteri plugin types) instead.
+		 *
+		 * ```js
+		 * // astro.config.mjs
+		 * import { defineConfig } from 'astro/config';
+		 *
+		 * export default defineConfig({
+		 *   experimental: {
+		 *     nativeMarkdown: true,
+		 *   },
+		 * });
+		 * ```
+		 *
+		 * You can also pass satteri plugins and enable additional parser features:
+		 *
+		 * ```js
+		 * // astro.config.mjs
+		 * import { defineConfig } from 'astro/config';
+		 *
+		 * export default defineConfig({
+		 *   experimental: {
+		 *     nativeMarkdown: {
+		 *       hastPlugins: [myPlugin],
+		 *       features: {
+		 *         directive: true,
+		 *         definitionList: true,
+		 *       },
+		 *     },
+		 *   },
+		 * });
+		 * ```
+		 */
+		nativeMarkdown?: boolean | {
+			mdastPlugins?: import('satteri').MdastPluginDefinition[];
+			hastPlugins?: import('satteri').HastPluginDefinition[];
+			features?: import('satteri').Features;
+		};
+
 		/**
 		 * @name experimental.queuedRendering
 		 * @type {boolean | { poolSize?: number; cache?: boolean }}

packages/astro/src/vite-plugin-markdown/content-entry-type.ts

@@ -1,5 +1,5 @@
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { createMarkdownProcessor } from '@astrojs/markdown-remark';
+import { createMarkdownProcessor, createSatteriMarkdownProcessor } from '@astrojs/markdown-remark';
 import { safeParseFrontmatter } from '../content/utils.js';
 import type { ContentEntryType } from '../types/public/content.js';
 
@@ -18,10 +18,23 @@ export const markdownContentEntryType: ContentEntryType = {
 	handlePropagation: true,
 
 	async getRenderFunction(config) {
-		const processor = await createMarkdownProcessor({
-			image: config.image,
-			...config.markdown,
-		});
+		const nativeMd = config.experimental.nativeMarkdown;
+		let processor;
+		if (nativeMd) {
+			const nativeOpts = typeof nativeMd === 'object' ? nativeMd : undefined;
+			processor = await createSatteriMarkdownProcessor({
+				image: config.image,
+				...config.markdown,
+				mdastPlugins: nativeOpts?.mdastPlugins,
+				hastPlugins: nativeOpts?.hastPlugins,
+				features: nativeOpts?.features,
+			});
+		} else {
+			processor = await createMarkdownProcessor({
+				image: config.image,
+				...config.markdown,
+			});
+		}
 		return async function renderToString(entry) {
 			// Process markdown even if it's empty as remark/rehype plugins may add content or frontmatter dynamically
 			const result = await processor.render(entry.body ?? '', {

packages/astro/src/vite-plugin-markdown/index.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
 	createMarkdownProcessor,
+	createSatteriMarkdownProcessor,
 	isFrontmatterValid,
 	type MarkdownProcessor,
 } from '@astrojs/markdown-remark';
@@ -81,10 +82,22 @@ export default function markdown({ settings, logger }: AstroPluginOptions): Plug
 
 				// Lazily initialize the Markdown processor
 				if (!processor) {
-					processor = createMarkdownProcessor({
-						image: settings.config.image,
-						...settings.config.markdown,
-					});
+					const nativeMd = settings.config.experimental.nativeMarkdown;
+					if (nativeMd) {
+						const nativeOpts = typeof nativeMd === 'object' ? nativeMd : undefined;
+						processor = createSatteriMarkdownProcessor({
+							image: settings.config.image,
+							...settings.config.markdown,
+							mdastPlugins: nativeOpts?.mdastPlugins,
+							hastPlugins: nativeOpts?.hastPlugins,
+							features: nativeOpts?.features,
+						});
+					} else {
+						processor = createMarkdownProcessor({
+							image: settings.config.image,
+							...settings.config.markdown,
+						});
+					}
 				}
 
 				const renderResult = await (await processor).render(raw.content, {

packages/integrations/mdx/package.json

@@ -39,11 +39,13 @@
     "acorn": "^8.16.0",
     "es-module-lexer": "^2.0.0",
     "estree-util-visit": "^2.0.0",
+    "github-slugger": "^2.0.0",
     "hast-util-to-html": "^9.0.5",
     "piccolore": "^0.1.3",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
     "remark-smartypants": "^3.0.2",
+    "satteri": "^0.2.7",
     "source-map": "^0.7.6",
     "unist-util-visit": "^5.1.0",
     "vfile": "^6.0.3"
@@ -52,8 +54,8 @@
     "astro": "^7.0.0-alpha.0"
   },
   "devDependencies": {
-    "@shikijs/rehype": "^4.0.2",
-    "@shikijs/twoslash": "^4.0.2",
+    "@shikijs/rehype": "^4.0.0",
+    "@shikijs/twoslash": "^4.0.0",
     "@types/estree": "^1.0.8",
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
@@ -74,8 +76,5 @@
   },
   "engines": {
     "node": ">=22.12.0"
-  },
-  "publishConfig": {
-    "provenance": true
   }
 }

packages/integrations/mdx/src/index.ts

@@ -10,7 +10,7 @@ import type {
 } from 'astro';
 import type { Options as RemarkRehypeOptions } from 'remark-rehype';
 import type { PluggableList } from 'unified';
-import type { OptimizeOptions } from './rehype-optimize-static.js';
+import type { MdastPluginDefinition, HastPluginDefinition } from './satteri-plugins.js';
 import { ignoreStringPlugins, safeParseFrontmatter } from './utils.js';
 import { type VitePluginMdxOptions, vitePluginMdx } from './vite-plugin-mdx.js';
 import { vitePluginMdxPostprocess } from './vite-plugin-mdx-postprocess.js';
@@ -23,7 +23,10 @@ export type MdxOptions = Omit<typeof markdownConfigDefaults, 'remarkPlugins' | '
 	remarkPlugins: PluggableList;
 	rehypePlugins: PluggableList;
 	remarkRehype: RemarkRehypeOptions;
-	optimize: boolean | OptimizeOptions;
+	optimize: boolean | { ignoreElementNames?: string[] };
+	mdastPlugins: MdastPluginDefinition[];
+	hastPlugins: HastPluginDefinition[];
+	features?: import('satteri').Features;
 };
 
 type SetupHookParams = HookParameters<'astro:config:setup'> & {
@@ -97,10 +100,32 @@ export default function mdx(partialMdxOptions: Partial<MdxOptions> = {}): AstroI
 					),
 				});
 
+				const nativeMd = config.experimental.nativeMarkdown;
+
+				// When nativeMarkdown is enabled, merge mdastPlugins/hastPlugins/features from the experimental config
+				if (nativeMd && extendMarkdownConfig) {
+					const nativeOpts = typeof nativeMd === 'object' ? nativeMd : undefined;
+					resolvedMdxOptions.mdastPlugins = [
+						...(nativeOpts?.mdastPlugins ?? []),
+						...resolvedMdxOptions.mdastPlugins,
+					];
+					resolvedMdxOptions.hastPlugins = [
+						...(nativeOpts?.hastPlugins ?? []),
+						...resolvedMdxOptions.hastPlugins,
+					];
+					if (nativeOpts?.features || resolvedMdxOptions.features) {
+						resolvedMdxOptions.features = {
+							...nativeOpts?.features,
+							...resolvedMdxOptions.features,
+						};
+					}
+				}
+
 				// Mutate `mdxOptions` so that `vitePluginMdx` can reference the actual options
 				Object.assign(vitePluginMdxOptions, {
 					mdxOptions: resolvedMdxOptions,
 					srcDir: config.srcDir,
+					nativeMarkdown: nativeMd,
 				});
 				// @ts-expect-error After we assign, we don't need to reference `mdxOptions` in this context anymore.
 				// Re-assign it so that the garbage can be collected later.
@@ -114,6 +139,8 @@ const defaultMdxOptions = {
 	extendMarkdownConfig: true,
 	recmaPlugins: [],
 	optimize: false,
+	mdastPlugins: [],
+	hastPlugins: [],
 } satisfies Partial<MdxOptions>;
 
 function markdownConfigToMdxOptions(
@@ -147,5 +174,8 @@ function applyDefaultOptions({
 		rehypePlugins: options.rehypePlugins ?? defaults.rehypePlugins,
 		shikiConfig: options.shikiConfig ?? defaults.shikiConfig,
 		optimize: options.optimize ?? defaults.optimize,
+		mdastPlugins: options.mdastPlugins ?? defaults.mdastPlugins,
+		hastPlugins: options.hastPlugins ?? defaults.hastPlugins,
+		features: options.features ?? defaults.features,
 	};
 }