feat(satteri): Use the Sätteri databag for data

.changeset/satteri-ctx-data-metadata.md

@@ -0,0 +1,8 @@
+---
+'@astrojs/markdown-satteri': patch
+'@astrojs/mdx': minor
+---
+
+Adds support for [modifying frontmatter programmatically](https://docs.astro.build/en/guides/markdown-content/#modifying-frontmatter-programmatically) with the default Markdown processor.
+
+A Sätteri plugin can now read and mutate `ctx.data.astro.frontmatter`, and Astro uses the result as the page's frontmatter, in both Markdown and MDX.

packages/integrations/mdx/package.json

@@ -77,7 +77,7 @@
     "remark-math": "^6.0.0",
     "remark-rehype": "^11.1.2",
     "remark-toc": "^9.0.0",
-    "satteri": "^0.9.0",
+    "satteri": "^0.9.1",
     "shiki": "^4.0.2",
     "unified": "^11.0.5",
     "vite": "^8.0.13"

packages/integrations/mdx/src/satteri/hast-astro-metadata.ts

@@ -1,5 +1,5 @@
 import type { AstroMetadata } from '@astrojs/internal-helpers/markdown';
-import { resolvePath } from 'astro/markdown';
+import { createDefaultAstroMetadata, resolvePath } from 'astro/markdown';
 import type { Identifier, Literal } from 'estree';
 import {
 	defineHastPlugin,
@@ -11,6 +11,12 @@ import { findAttrValue, hasDirective, isComponent, type MdxJsxHastNode } from '.
 
 export type { AstroMetadata };
 
+declare module 'satteri' {
+	interface DataMap {
+		__astroMetadata: AstroMetadata;
+	}
+}
+
 type ImportSpecifier = { local: string; imported: string };
 type MatchedImport = { name: string; path: string };
 
@@ -83,7 +89,6 @@ function findMatchingImport(
 function processJsxNode(
 	node: MdxJsxHastNode,
 	ctx: HastVisitorContext,
-	metadata: AstroMetadata,
 	imports: Map<string, Set<ImportSpecifier>>,
 	filePath: string,
 ) {
@@ -118,6 +123,7 @@ function processJsxNode(
 	const exportName =
 		matchedImport.name === '*' ? tagName.split('.').slice(1).join('.') : matchedImport.name;
 
+	const metadata = (ctx.data.__astroMetadata ??= createDefaultAstroMetadata());
 	if (hasClient && findAttrValue(node, 'client:only') !== null) {
 		metadata.clientOnlyComponents.push({
 			exportName: matchedImport.name,
@@ -152,10 +158,7 @@ function processJsxNode(
 	}
 }
 
-export function createAstroMetadataPlugin(
-	metadata: AstroMetadata,
-	filePath: string,
-): HastPluginDefinition {
+export function createAstroMetadataPlugin(filePath: string): HastPluginDefinition {
 	const imports = new Map<string, Set<ImportSpecifier>>();
 	return defineHastPlugin({
 		name: 'astro-metadata',
@@ -169,14 +172,14 @@ export function createAstroMetadataPlugin(
 		mdxJsxFlowElement: {
 			filter: [],
 			visit(node, ctx) {
-				processJsxNode(node, ctx, metadata, imports, filePath);
+				processJsxNode(node, ctx, imports, filePath);
 			},
 		},
 
 		mdxJsxTextElement: {
 			filter: [],
 			visit(node, ctx) {
-				processJsxNode(node, ctx, metadata, imports, filePath);
+				processJsxNode(node, ctx, imports, filePath);
 			},
 		},
 	});

packages/integrations/mdx/src/satteri/hast-images-to-component.ts

@@ -13,21 +13,20 @@ export interface ImageImportInfo {
 }
 
 export function createImageToComponentPlugin(
-	localImagePaths: Set<string>,
-	remoteImagePaths: Set<string>,
 	imageImportInfo: ImageImportInfo,
 ): HastPluginDefinition {
 	return defineHastPlugin({
 		name: 'image-to-component',
 		element: {
 			filter: ['img'],
-			visit(node) {
+			visit(node, ctx) {
 				const src = node.properties?.src;
 				if (typeof src !== 'string') return;
 
 				const decodedSrc = decodeURI(src);
-				const isLocal = localImagePaths.has(decodedSrc);
-				const isRemote = remoteImagePaths.has(decodedSrc);
+				const astro = ctx.data.astro;
+				const isLocal = astro?.localImagePaths.has(decodedSrc) ?? false;
+				const isRemote = astro?.remoteImagePaths.has(decodedSrc) ?? false;
 				if (!isLocal && !isRemote) return;
 
 				const attrs: MdxJsxAttributeNode[] = [];

packages/integrations/mdx/src/satteri/index.ts

@@ -1,6 +1,7 @@
 import { pathToFileURL } from 'node:url';
+import { isFrontmatterValid } from '@astrojs/internal-helpers/frontmatter';
 import type { MarkdownHeading } from '@astrojs/internal-helpers/markdown';
-import type { SatteriResolvedOptions } from '@astrojs/markdown-satteri';
+import type { SatteriAstroData, SatteriResolvedOptions } from '@astrojs/markdown-satteri';
 import {
 	satteriCollectImagesPlugin,
 	satteriCreateHighlightFn,
@@ -67,32 +68,28 @@ export function createMdxProcessor(
 			}
 			if (initPromise) await initPromise;
 
-			const headings: MarkdownHeading[] = [];
-			const localImagePaths = new Set<string>();
-			const remoteImagePaths = new Set<string>();
-
-			const astroMetadata = createDefaultAstroMetadata();
+			const astroData: SatteriAstroData = {
+				frontmatter,
+				headings: [],
+				localImagePaths: new Set(),
+				remoteImagePaths: new Set(),
+			};
 
-			const collectImages = satteriCollectImagesPlugin(localImagePaths, remoteImagePaths);
-			const headingIds = satteriHeadingIdsPlugin(headings, frontmatter);
-			const astroMeta = createAstroMetadataPlugin(astroMetadata, filePath);
+			const collectImages = satteriCollectImagesPlugin();
+			const headingIds = satteriHeadingIdsPlugin();
+			const astroMeta = createAstroMetadataPlugin(filePath);
 			const imageImportInfo: ImageImportInfo = {
 				importedImages: new Map(),
 				hasImages: false,
 			};
-			const imageToComponent = createImageToComponentPlugin(
-				localImagePaths,
-				remoteImagePaths,
-				imageImportInfo,
-			);
+			const imageToComponent = createImageToComponentPlugin(imageImportInfo);
 
 			const syntaxHighlight = mdxOptions.syntaxHighlight;
 			const excludeLangs =
 				typeof syntaxHighlight === 'object' ? syntaxHighlight.excludeLangs : undefined;
 
-			const allMdastPlugins: MdastPluginDefinition[] = satteriOptions.mdastPlugins.length
-				? [collectImages, ...satteriOptions.mdastPlugins]
-				: [collectImages];
+			// Collect last so image-URL rewrites by user plugins are captured.
+			const allMdastPlugins: MdastPluginDefinition[] = [...satteriOptions.mdastPlugins, collectImages];
 
 			const hastPlugins: HastPluginDefinition[] = [];
 			if (highlightFn) {
@@ -136,9 +133,23 @@ export function createMdxProcessor(
 				},
 				fileURL: pathToFileURL(filePath),
 				jsxImportSource: 'astro',
+				data: { astro: astroData },
 			});
 			let compiled = mdxResult.code;
 
+			// Read the returned bag, not the seeded reference, so a plugin that replaces it is honored.
+			const astro = mdxResult.data.astro;
+			const headings = astro?.headings ?? [];
+			const astroMetadata = mdxResult.data.__astroMetadata ?? createDefaultAstroMetadata();
+
+			// Plugins may have mutated frontmatter; emit the final value.
+			const resolvedFrontmatter = astro?.frontmatter;
+			if (!resolvedFrontmatter || !isFrontmatterValid(resolvedFrontmatter)) {
+				throw new Error(
+					'[MDX] A Sätteri plugin attempted to inject invalid frontmatter. Ensure `ctx.data.astro.frontmatter` is a valid object that is not `null` or `undefined`.',
+				);
+			}
+
 			compiled = compiled.replace(/^export default MDXContent;\s*$/m, '');
 
 			if (imageImportInfo.hasImages) {
@@ -152,14 +163,14 @@ export function createMdxProcessor(
 				compiled += `\nexport const ${USES_ASTRO_IMAGE_FLAG} = true;`;
 			}
 
-			compiled += `\nexport const frontmatter = ${JSON.stringify(frontmatter)};`;
+			compiled += `\nexport const frontmatter = ${JSON.stringify(resolvedFrontmatter)};`;
 			compiled += `\nexport function getHeadings() { return ${JSON.stringify(headings)}; }`;
 
-			if (frontmatter.layout) {
+			if (resolvedFrontmatter.layout) {
 				compiled = compiled.replace(/^function MDXContent\(/m, 'function __OriginalMDXContent__(');
 				compiled += `
 import { jsx as __astro_layout_jsx__ } from 'astro/jsx-runtime';
-import __astro_layout_component__ from ${JSON.stringify(frontmatter.layout)};
+import __astro_layout_component__ from ${JSON.stringify(resolvedFrontmatter.layout)};
 export default function MDXContent(props) {
 	const content = __OriginalMDXContent__(props);
 	const { layout, ...frontmatterContent } = frontmatter;

packages/integrations/mdx/test/fixtures/mdx-get-headings/src/pages/pages.json.js

@@ -1,8 +1,8 @@
 export async function GET() {
 	const mdxPages = await import.meta.glob('./*.mdx', { eager: true });
+	const entries = Object.entries(mdxPages ?? {});
 	return Response.json({
-		headingsByPage: Object.fromEntries(
-			Object.entries(mdxPages ?? {}).map(([k, v]) => [k, v?.getHeadings()])
-		),
+		headingsByPage: Object.fromEntries(entries.map(([k, v]) => [k, v?.getHeadings()])),
+		frontmatterByPage: Object.fromEntries(entries.map(([k, v]) => [k, v?.frontmatter])),
 	});
 }

packages/integrations/mdx/test/mdx-satteri.test.ts

@@ -3,8 +3,16 @@ import { before, describe, it } from 'node:test';
 import mdx from '@astrojs/mdx';
 import { satteri } from '@astrojs/markdown-satteri';
 import { parseHTML } from 'linkedom';
+import type { MdastPluginDefinition } from 'satteri';
 import { loadFixture, type Fixture } from './test-utils.ts';
 
+const injectFrontmatter: MdastPluginDefinition = {
+	name: 'inject-frontmatter',
+	heading(_node, ctx) {
+		ctx.data.astro!.frontmatter.injected = 'from-plugin';
+	},
+};
+
 describe('MDX with the Sätteri processor', () => {
 	let fixture: Fixture;
 
@@ -13,7 +21,7 @@ describe('MDX with the Sätteri processor', () => {
 			root: new URL('./fixtures/mdx-get-headings/', import.meta.url),
 			integrations: [mdx()],
 			markdown: {
-				processor: satteri(),
+				processor: satteri({ mdastPlugins: [injectFrontmatter] }),
 			},
 		});
 
@@ -37,4 +45,11 @@ describe('MDX with the Sätteri processor', () => {
 		assert.ok(slugs.includes('section-1'));
 		assert.ok(slugs.includes('section-2'));
 	});
+
+	it('lets a Sätteri plugin modify frontmatter, exposed via the page export', async () => {
+		const { frontmatterByPage } = JSON.parse(await fixture.readFile('/pages.json'));
+		assert.equal(frontmatterByPage['./test.mdx'].injected, 'from-plugin');
+		assert.equal(frontmatterByPage['./test-with-frontmatter.mdx'].injected, 'from-plugin');
+		assert.equal(frontmatterByPage['./test-with-frontmatter.mdx'].title, 'The Frontmatter Title');
+	});
 });

packages/markdown/satteri/package.json

@@ -29,7 +29,7 @@
     "@astrojs/internal-helpers": "workspace:*",
     "@astrojs/prism": "workspace:*",
     "github-slugger": "^2.0.0",
-    "satteri": "^0.9.0"
+    "satteri": "^0.9.1"
   },
   "devDependencies": {
     "astro-scripts": "workspace:*"

packages/markdown/satteri/src/index.ts

@@ -8,6 +8,7 @@ export {
 	createHighlightFn as satteriCreateHighlightFn,
 	collectHastText as satteriCollectHastText,
 	makeFragmentNode as satteriMakeFragmentNode,
+	type SatteriAstroData,
 	createSatteriMarkdownProcessor,
 	type SatteriMarkdownProcessorOptions,
 } from './satteri-processor.js';