[MDX] Support YAML frontmatter (#3995)

* chore: remove old comment

* deps: add remark-frontmatter

* deps: add remark-mdx-frontmatter

* fix: handle null or undefined frontmatter key

* feat: configure frontmatter plugins with defaults

* test: frontmatter and custom frontmatter name

* docs: add frontmatterOptions config

* docs: add "variables" and "frontmatter" docs

* chore: excessible -> accessible

* chore: changeset

* chore: remove bad mdx comment

.changeset/silent-clocks-pump.md

@@ -0,0 +1,6 @@
+---
+'@astrojs/mdx': minor
+'astro': patch
+---
+
+Support YAML frontmatter in MDX files

packages/astro/src/core/build/generate.ts

@@ -59,7 +59,7 @@ function shouldSkipDraft(pageModule: ComponentInstance, astroConfig: AstroConfig
 		!astroConfig.markdown.drafts &&
 		// This is a draft post
 		'frontmatter' in pageModule &&
-		(pageModule as any).frontmatter.draft === true
+		(pageModule as any).frontmatter?.draft === true
 	);
 }
 

packages/integrations/mdx/README.md

@@ -78,6 +78,62 @@ To write your first MDX page in Astro, head to our [UI framework documentation][
 
 Also check our [Astro Integration Documentation][astro-integration] for more on integrations.
 
+### Variables
+
+MDX supports `export` statements to add variables to your templates. These variables are accessible both from the template itself _and_ as named properties when importing the template somewhere else.
+
+For instance, you can export a `title` field from an MDX page or component to use as a heading with `{JSX expressions}`:
+
+```mdx
+export const title = 'My first MDX post'
+
+# {title}
+```
+
+This `title` will be accessible from `import` and [glob](https://docs.astro.build/en/reference/api-reference/#astroglob) statements as well:
+
+```astro
+---
+// src/pages/index.astro
+const posts = await Astro.glob('./*.mdx');
+---
+
+{posts.map(post => <p>{post.title}</p>)}
+```
+
+See [the official "how MDX works" guide](https://mdxjs.com/docs/using-mdx/#how-mdx-works) for more on MDX variables.
+
+### Frontmatter
+
+Astro also supports YAML-based frontmatter out-of-the-box using the [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) plugin. By default, all variables declared in a frontmatter fence (`---`) will be accessible via the `frontmatter` export. See the `frontmatterOptions` configuration to customize this behavior.
+
+For example, we can add a `title` and `publishDate` to an MDX page or component like so:
+
+```mdx
+---
+title: 'My first MDX post'
+publishDate: '21 September 2022'
+---
+
+# {frontmatter.title}
+```
+
+Now, this `title` and `publishDate` will be accessible from `import` and [glob](https://docs.astro.build/en/reference/api-reference/#astroglob) statements via the `frontmatter` property. This matches the behavior of [plain markdown in Astro](https://docs.astro.build/en/reference/api-reference/#markdown-files) as well!
+
+```astro
+---
+// src/pages/index.astro
+const posts = await Astro.glob('./*.mdx');
+---
+
+{posts.map(post => (
+  <Fragment>
+    <h2>{post.frontmatter.title}</h2>
+    <time>{post.frontmatter.publishDate}</time>
+  </Fragment>
+))}
+```
+
 ## Configuration
 
 <details>
@@ -140,6 +196,37 @@ export default {
 ```
 </details>
 
+<details>
+  <summary><strong>frontmatterOptions</strong></summary>
+
+**Default:** `{ name: 'frontmatter' }`
+
+We use [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) to parse YAML-based frontmatter in your MDX files. If you want to override our default configuration or extend remark-mdx-frontmatter (ex. to [apply a custom frontmatter parser](https://github.com/remcohaszing/remark-mdx-frontmatter#parsers)), you can supply a `frontmatterOptions` configuration.
+
+For example, say you want to access frontmatter as root-level variables without a nested `frontmatter` object. You can override the [`name` configuration option](https://github.com/remcohaszing/remark-mdx-frontmatter#name) like so:
+
+```js
+// astro.config.mjs
+export default {
+  integrations: [mdx({
+    frontmatterOptions: {
+      name: '',
+    }
+  })],
+}
+```
+
+```mdx
+---
+title: I'm just a variable now!
+---
+
+# {title}
+```
+
+See the [remark-mdx-frontmatter README](https://github.com/remcohaszing/remark-mdx-frontmatter#options) for a complete list of options.
+</details>
+
 ## Examples
 
 - The [Astro MDX example](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use MDX files in your Astro project.

packages/integrations/mdx/package.json

@@ -32,7 +32,9 @@
   "dependencies": {
     "@mdx-js/rollup": "^2.1.1",
     "es-module-lexer": "^0.10.5",
+    "remark-frontmatter": "^4.0.1",
     "remark-gfm": "^3.0.1",
+    "remark-mdx-frontmatter": "^2.0.2",
     "remark-smartypants": "^2.0.0"
   },
   "devDependencies": {

packages/integrations/mdx/src/index.ts

@@ -1,23 +1,32 @@
 import mdxPlugin, { Options as MdxRollupPluginOptions } from '@mdx-js/rollup';
 import type { AstroIntegration } from 'astro';
+import type { RemarkMdxFrontmatterOptions } from 'remark-mdx-frontmatter';
 import { parse as parseESM } from 'es-module-lexer';
 import remarkGfm from 'remark-gfm';
 import remarkSmartypants from 'remark-smartypants';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
 import { getFileInfo } from './utils.js';
 
 type WithExtends<T> = T | { extends: T };
 
 type MdxOptions = {
 	remarkPlugins?: WithExtends<MdxRollupPluginOptions['remarkPlugins']>;
 	rehypePlugins?: WithExtends<MdxRollupPluginOptions['rehypePlugins']>;
-};
+	/**
+	 * Configure the remark-mdx-frontmatter plugin
+	 * @see https://github.com/remcohaszing/remark-mdx-frontmatter#options for a full list of options
+	 * @default {{ name: 'frontmatter' }}
+	 */
+	 frontmatterOptions?: RemarkMdxFrontmatterOptions;
+}
 
 const DEFAULT_REMARK_PLUGINS = [remarkGfm, remarkSmartypants];
 
 function handleExtends<T>(
 	config: WithExtends<T[] | undefined>,
-	defaults: T[] = []
-): T[] | undefined {
+	defaults: T[] = [],
+): T[] {
 	if (Array.isArray(config)) return config;
 
 	return [...defaults, ...(config?.extends ?? [])];
@@ -35,9 +44,18 @@ export default function mdx(mdxOptions: MdxOptions = {}): AstroIntegration {
 							{
 								enforce: 'pre',
 								...mdxPlugin({
-									remarkPlugins: handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS),
+									remarkPlugins: [
+										...handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS),
+										// Frontmatter plugins should always be applied!
+										// We can revisit this if a strong use case to *remove*
+										// YAML frontmatter via config is reported.
+										remarkFrontmatter,
+										[remarkMdxFrontmatter, {
+											name: 'frontmatter',
+											...mdxOptions.frontmatterOptions,
+										}],
+									],
 									rehypePlugins: handleExtends(mdxOptions.rehypePlugins),
-									// place these after so the user can't override
 									jsx: true,
 									jsxImportSource: 'astro',
 									// Note: disable `.md` support

packages/integrations/mdx/test/fixtures/mdx-custom-frontmatter-name/src/pages/glob.json.js

@@ -0,0 +1,9 @@
+export async function get() {
+	const mdxPages = await import.meta.glob('./*.mdx', { eager: true });
+
+	return {
+		body: JSON.stringify({
+			titles: Object.values(mdxPages ?? {}).map(v => v?.customFrontmatter?.title),
+		})
+	}
+}

packages/integrations/mdx/test/fixtures/mdx-custom-frontmatter-name/src/pages/index.mdx

@@ -0,0 +1,6 @@
+---
+title: 'Using YAML frontmatter'
+illThrowIfIDontExist: "Oh no, that's scary!"
+---
+
+# {customFrontmatter.illThrowIfIDontExist}

packages/integrations/mdx/test/fixtures/mdx-frontmatter/src/pages/glob.json.js

@@ -0,0 +1,9 @@
+export async function get() {
+	const mdxPages = await import.meta.glob('./*.mdx', { eager: true });
+
+	return {
+		body: JSON.stringify({
+			titles: Object.values(mdxPages ?? {}).map(v => v?.frontmatter?.title),
+		})
+	}
+}

packages/integrations/mdx/test/fixtures/mdx-frontmatter/src/pages/index.mdx

@@ -0,0 +1,6 @@
+---
+title: 'Using YAML frontmatter'
+illThrowIfIDontExist: "Oh no, that's scary!"
+---
+
+# {frontmatter.illThrowIfIDontExist}

packages/integrations/mdx/test/mdx-frontmatter.js

@@ -0,0 +1,43 @@
+import mdx from '@astrojs/mdx';
+
+import { expect } from 'chai';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+
+const FIXTURE_ROOT = new URL('./fixtures/mdx-frontmatter/', import.meta.url);
+
+describe('MDX frontmatter', () => {
+	it('builds when "frontmatter.property" is in JSX expression', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [mdx()],
+		});
+		await fixture.build();
+		expect(true).to.equal(true);
+	});
+
+	it('extracts frontmatter to "frontmatter" export', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [mdx()],
+		});
+		await fixture.build();
+
+		const { titles } = JSON.parse(await fixture.readFile('/glob.json'));
+		expect(titles).to.include('Using YAML frontmatter');
+	});
+
+	it('extracts frontmatter to "customFrontmatter" export when configured', async () => {
+		const fixture = await loadFixture({
+			root: new URL('./fixtures/mdx-custom-frontmatter-name/', import.meta.url),
+			integrations: [mdx({
+				frontmatterOptions: {
+					name: 'customFrontmatter',
+				},
+			})],
+		});
+		await fixture.build();
+
+		const { titles } = JSON.parse(await fixture.readFile('/glob.json'));
+		expect(titles).to.include('Using YAML frontmatter');
+	});
+});