[MDX] Extend Markdown plugin config, with customization options (#4504)

* test: new combined remark / rehype suite

* fix: use with-plugins fixture

* chore: remove old mdx plugin tests

* docs: add JS docs

* docs: update README with thorough example

* chore: changeset

* fix: add "extends" error message

* fix: ignore string-based plugins in md

* feat: add warning log for string plugins

* docs: highlight `extendPlugins`

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* nit: highlight "extendPlugins"

* fix: md plugins type check

* chore: "defaults" -> "astroDefaults"

* nit: info log when inheriting markdown plugins

* refactor: one big log on new behavior

* dan: dan nit

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

1 files changed, 125 insertions, 2 deletions

diff --git a/packages/integrations/mdx/src/utils.ts b/packages/integrations/mdx/src/utils.ts
index f5135ebc2..dc7879dd8 100644
--- a/packages/integrations/mdx/src/utils.ts
+++ b/packages/integrations/mdx/src/utils.ts
@@ -1,10 +1,33 @@
 import type { Options as AcornOpts } from 'acorn';
-import { parse } from 'acorn';
 import type { AstroConfig, SSRError } from 'astro';
 import type { MdxjsEsm } from 'mdast-util-mdx';
-
+import type { PluggableList } from '@mdx-js/mdx/lib/core.js';
+import type { Options as MdxRollupPluginOptions } from '@mdx-js/rollup';
+import { bold, yellow } from 'kleur/colors';
+import { nodeTypes } from '@mdx-js/mdx';
+import { parse } from 'acorn';
+import rehypeRaw from 'rehype-raw';
+import remarkGfm from 'remark-gfm';
+import remarkSmartypants from 'remark-smartypants';
+import { remarkInitializeAstroData } from './astro-data-utils.js';
+import rehypeCollectHeadings from './rehype-collect-headings.js';
+import remarkPrism from './remark-prism.js';
+import remarkShiki from './remark-shiki.js';
 import matter from 'gray-matter';
 
+export type MdxOptions = {
+	remarkPlugins?: PluggableList;
+	rehypePlugins?: PluggableList;
+	/**
+	 * Choose which remark and rehype plugins to inherit, if any.
+	 *
+	 * - "markdown" (default) - inherit your project’s markdown plugin config ([see Markdown docs](https://docs.astro.build/en/guides/markdown-content/#configuring-markdown))
+	 * - "astroDefaults" - inherit Astro’s default plugins only ([see defaults](https://docs.astro.build/en/reference/configuration-reference/#markdownextenddefaultplugins))
+	 * - false - do not inherit any plugins
+	 */
+	extendPlugins?: 'markdown' | 'astroDefaults' | false;
+};
+
 function appendForwardSlash(path: string) {
 	return path.endsWith('/') ? path : path + '/';
 }
@@ -14,6 +37,9 @@ interface FileInfo {
 	fileUrl: string;
 }
 
+const DEFAULT_REMARK_PLUGINS: PluggableList = [remarkGfm, remarkSmartypants];
+const DEFAULT_REHYPE_PLUGINS: PluggableList = [];
+
 /** @see 'vite-plugin-utils' for source */
 export function getFileInfo(id: string, config: AstroConfig): FileInfo {
 	const sitePathname = appendForwardSlash(
@@ -83,3 +109,100 @@ export function jsToTreeNode(
 		},
 	};
 }
+
+export async function getRemarkPlugins(
+	mdxOptions: MdxOptions,
+	config: AstroConfig
+): Promise<MdxRollupPluginOptions['remarkPlugins']> {
+	let remarkPlugins: PluggableList = [
+		// Set "vfile.data.astro" for plugins to inject frontmatter
+		remarkInitializeAstroData,
+	];
+	switch (mdxOptions.extendPlugins) {
+		case false:
+			break;
+		case 'astroDefaults':
+			remarkPlugins = [...remarkPlugins, ...DEFAULT_REMARK_PLUGINS];
+			break;
+		default:
+			remarkPlugins = [
+				...remarkPlugins,
+				...(config.markdown.extendDefaultPlugins ? DEFAULT_REMARK_PLUGINS : []),
+				...ignoreStringPlugins(config.markdown.remarkPlugins ?? []),
+			];
+			break;
+	}
+	if (config.markdown.syntaxHighlight === 'shiki') {
+		remarkPlugins.push([await remarkShiki(config.markdown.shikiConfig)]);
+	}
+	if (config.markdown.syntaxHighlight === 'prism') {
+		remarkPlugins.push(remarkPrism);
+	}
+
+	remarkPlugins = [...remarkPlugins, ...(mdxOptions.remarkPlugins ?? [])];
+	return remarkPlugins;
+}
+
+export function getRehypePlugins(
+	mdxOptions: MdxOptions,
+	config: AstroConfig
+): MdxRollupPluginOptions['rehypePlugins'] {
+	let rehypePlugins: PluggableList = [
+		// getHeadings() is guaranteed by TS, so we can't allow user to override
+		rehypeCollectHeadings,
+		// rehypeRaw allows custom syntax highlighters to work without added config
+		[rehypeRaw, { passThrough: nodeTypes }] as any,
+	];
+	switch (mdxOptions.extendPlugins) {
+		case false:
+			break;
+		case 'astroDefaults':
+			rehypePlugins = [...rehypePlugins, ...DEFAULT_REHYPE_PLUGINS];
+			break;
+		default:
+			rehypePlugins = [
+				...rehypePlugins,
+				...(config.markdown.extendDefaultPlugins ? DEFAULT_REHYPE_PLUGINS : []),
+				...ignoreStringPlugins(config.markdown.rehypePlugins ?? []),
+			];
+			break;
+	}
+
+	rehypePlugins = [...rehypePlugins, ...(mdxOptions.rehypePlugins ?? [])];
+	return rehypePlugins;
+}
+
+function ignoreStringPlugins(plugins: any[]) {
+	let validPlugins: PluggableList = [];
+	let hasInvalidPlugin = false;
+	for (const plugin of plugins) {
+		if (typeof plugin === 'string') {
+			console.warn(yellow(`[MDX] ${bold(plugin)} not applied.`));
+			hasInvalidPlugin = true;
+		} else if (Array.isArray(plugin) && typeof plugin[0] === 'string') {
+			console.warn(yellow(`[MDX] ${bold(plugin[0])} not applied.`));
+			hasInvalidPlugin = true;
+		} else {
+			validPlugins.push(plugin);
+		}
+	}
+	if (hasInvalidPlugin) {
+		console.warn(
+			`To inherit Markdown plugins in MDX, please use explicit imports in your config instead of "strings." See Markdown docs: https://docs.astro.build/en/guides/markdown-content/#markdown-plugins`
+		);
+	}
+	return validPlugins;
+}
+
+// TODO: remove for 1.0
+export function handleExtendsNotSupported(pluginConfig: any) {
+	if (
+		typeof pluginConfig === 'object' &&
+		pluginConfig !== null &&
+		(pluginConfig as any).hasOwnProperty('extends')
+	) {
+		throw new Error(
+			`[MDX] The "extends" plugin option is no longer supported! Astro now extends your project's \`markdown\` plugin configuration by default. To customize this behavior, see the \`extendPlugins\` option instead: https://docs.astro.build/en/guides/integrations-guide/mdx/#extendplugins`
+		);
+	}
+}