feat: make Sätteri the default Markdown pipeline

.changeset/satteri-default-markdown-processor.md

@@ -0,0 +1,23 @@
+---
+'astro': major
+---
+
+Makes Sätteri the default Markdown processor
+
+Astro now renders `.md` files with `satteri()` from `@astrojs/markdown-satteri`, its native Markdown pipeline, instead of the remark/rehype pipeline. `@astrojs/markdown-remark` is no longer installed by default.
+
+To keep using the remark/rehype pipeline, install `@astrojs/markdown-remark` and set it as your processor:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
+
+export default defineConfig({
+  markdown: {
+    processor: unified(),
+  },
+});
+```
+
+The deprecated `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` options still work, but now require `@astrojs/markdown-remark` to be used.

knip.js

@@ -57,6 +57,9 @@ export default {
 				'rehype-toc',
 				'remark-code-titles',
 				'@types/http-cache-semantics',
+				// Optional peer dep: dynamically imported in config validation for the legacy
+				// remark/rehype pipeline. Knip flags it because it's referenced from source.
+				'@astrojs/markdown-remark',
 			],
 		},
 		'packages/astro-prism': {

packages/astro/package.json

@@ -39,7 +39,6 @@
     "./astro-jsx": "./astro-jsx.d.ts",
     "./tsconfigs/*.json": "./tsconfigs/*",
     "./tsconfigs/*": "./tsconfigs/*.json",
-    "./jsx/rehype.js": "./dist/jsx/rehype.js",
     "./jsx-runtime": {
       "types": "./jsx-runtime.d.ts",
       "default": "./dist/jsx-runtime/index.js"
@@ -136,7 +135,7 @@
   "dependencies": {
     "@astrojs/compiler-rs": "^0.1.10",
     "@astrojs/internal-helpers": "workspace:*",
-    "@astrojs/markdown-remark": "workspace:*",
+    "@astrojs/markdown-satteri": "workspace:*",
     "@astrojs/telemetry": "workspace:*",
     "@capsizecss/unpack": "^4.0.0",
     "@clack/prompts": "^1.1.0",
@@ -194,8 +193,17 @@
   "optionalDependencies": {
     "sharp": "^0.34.0"
   },
+  "peerDependencies": {
+    "@astrojs/markdown-remark": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@astrojs/markdown-remark": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@astrojs/check": "workspace:*",
+    "@astrojs/markdown-remark": "workspace:*",
     "@playwright/test": "1.58.2",
     "@types/aria-query": "^5.0.4",
     "@types/hast": "^3.0.4",
@@ -212,8 +220,6 @@
     "expect-type": "^1.3.0",
     "fs-fixture": "^2.13.0",
     "hono": "^4.12.14",
-    "mdast-util-mdx": "^3.0.0",
-    "mdast-util-mdx-jsx": "^3.2.0",
     "node-mocks-http": "^1.17.2",
     "parse-srcset": "^1.0.2",
     "rehype-autolink-headings": "^7.1.0",
@@ -242,7 +248,6 @@
       "./astro-jsx": "./astro-jsx.d.ts",
       "./tsconfigs/*.json": "./tsconfigs/*",
       "./tsconfigs/*": "./tsconfigs/*.json",
-      "./jsx/rehype.js": "./dist/jsx/rehype.js",
       "./jsx-runtime": {
         "types": "./jsx-runtime.d.ts",
         "default": "./dist/jsx-runtime/index.js"

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

@@ -9,7 +9,7 @@ import {
 	markdownConfigDefaults,
 	syntaxHighlightDefaults,
 } from '@astrojs/internal-helpers/markdown';
-import { unified } from '@astrojs/markdown-remark';
+import { satteri } from '@astrojs/markdown-satteri';
 import type { MarkdownProcessor } from '../../../markdown/index.js';
 import type { OutgoingHttpHeaders } from 'node:http';
 import { type BuiltinTheme, bundledThemes } from 'shiki';
@@ -418,7 +418,7 @@ export const AstroConfigSchema = z.object({
 				.default(ASTRO_CONFIG_DEFAULTS.markdown.remarkRehype),
 			// Deprecated: left undefined unless the user explicitly sets them, so the
 			// deprecation warning only fires when actually used. The active processor
-			// (`unified()`) supplies the real default (`gfm`/smart punctuation on) when
+			// (`satteri()`) supplies the real default (`gfm`/smart punctuation on) when
 			// these are absent.
 			gfm: z.boolean().optional(),
 			smartypants: z
@@ -448,7 +448,7 @@ export const AstroConfigSchema = z.object({
 				// A factory (not a shared value) so every config gets its own processor —
 				// integrations extend the pipeline by mutating `processor.options`, which
 				// would otherwise leak across configs built in the same process.
-				.default(() => unified()),
+				.default(() => satteri()),
 		})
 		.prefault({}),
 	vite: z

packages/astro/src/core/config/validate.ts

@@ -44,7 +44,7 @@ function warnDeprecatedMarkdownOptions(
 	const names = deprecated.map((key) => `\`markdown.${key}\``).join(' and ');
 	const isPlural = deprecated.length > 1;
 	console.warn(
-		`[astro] ${names} ${isPlural ? 'are' : 'is'} deprecated. Move ${isPlural ? 'them' : 'it'} onto your processor instead (e.g. \`unified({ gfm: false, smartypants: false })\`). Will be removed in a future major.`,
+		`[astro] ${names} ${isPlural ? 'are' : 'is'} deprecated. Move ${isPlural ? 'them' : 'it'} onto your processor instead (e.g. \`satteri({ features: { gfm: false, smartPunctuation: false } })\`, or \`unified({ gfm: false, smartypants: false })\` from \`@astrojs/markdown-remark\`). Will be removed in a future major.`,
 	);
 }
 
@@ -74,7 +74,15 @@ async function coerceLegacyMarkdownPlugins(
 		return;
 	}
 
-	const { unified, isUnifiedProcessor } = await import('@astrojs/markdown-remark');
+	let unified: typeof import('@astrojs/markdown-remark').unified;
+	let isUnifiedProcessor: typeof import('@astrojs/markdown-remark').isUnifiedProcessor;
+	try {
+		({ unified, isUnifiedProcessor } = await import('@astrojs/markdown-remark'));
+	} catch {
+		throw new Error(
+			'`markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` run on the `unified` processor from `@astrojs/markdown-remark`, which is no longer installed by default now that Sätteri is the default Markdown processor. Install it with:\n  npm install @astrojs/markdown-remark',
+		);
+	}
 
 	const current = md.processor;
 	if (!current || isUnifiedProcessor(current)) {