[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

1 files changed, 23 insertions, 5 deletions

diff --git a/packages/integrations/mdx/src/index.ts b/packages/integrations/mdx/src/index.ts
index d2525b6e9..d91f71c4b 100644
--- a/packages/integrations/mdx/src/index.ts
+++ b/packages/integrations/mdx/src/index.ts
@@ -1,8 +1,11 @@
 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 };
@@ -10,14 +13,20 @@ 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