@astrojs/mdx 0.2.1 → 0.4.0

package/src/index.ts

@@ -1,36 +1,143 @@
-import mdxPlugin from '@mdx-js/rollup';
+import { nodeTypes } from '@mdx-js/mdx';
+import mdxPlugin, { Options as MdxRollupPluginOptions } from '@mdx-js/rollup';
 import type { AstroIntegration } from 'astro';
+import { parse as parseESM } from 'es-module-lexer';
+import rehypeRaw from 'rehype-raw';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import type { RemarkMdxFrontmatterOptions } from 'remark-mdx-frontmatter';
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
+import remarkShikiTwoslash from 'remark-shiki-twoslash';
+import remarkSmartypants from 'remark-smartypants';
+import type { Plugin as VitePlugin } from 'vite';
+import remarkPrism from './remark-prism.js';
+import { getFileInfo, getFrontmatter } from './utils.js';
 
-export default function mdx(): AstroIntegration {
+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[] {
+	if (Array.isArray(config)) return config;
+
+	return [...defaults, ...(config?.extends ?? [])];
+}
+
+export default function mdx(mdxOptions: MdxOptions = {}): AstroIntegration {
 	return {
 		name: '@astrojs/mdx',
 		hooks: {
-			'astro:config:setup': ({ updateConfig, addPageExtension, command }: any) => {
+			'astro:config:setup': ({ updateConfig, config, addPageExtension, command }: any) => {
 				addPageExtension('.mdx');
+				let remarkPlugins = handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS);
+				let rehypePlugins = handleExtends(mdxOptions.rehypePlugins);
+
+				if (config.markdown.syntaxHighlight === 'shiki') {
+					remarkPlugins.push([
+						// Default export still requires ".default" chaining for some reason
+						// Workarounds tried:
+						// - "import * as remarkShikiTwoslash"
+						// - "import { default as remarkShikiTwoslash }"
+						(remarkShikiTwoslash as any).default,
+						config.markdown.shikiConfig,
+					]);
+					rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
+				}
+
+				if (config.markdown.syntaxHighlight === 'prism') {
+					remarkPlugins.push(remarkPrism);
+					rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
+				}
+
+				remarkPlugins.push(remarkFrontmatter);
+				remarkPlugins.push([
+					remarkMdxFrontmatter,
+					{
+						name: 'frontmatter',
+						...mdxOptions.frontmatterOptions,
+					},
+				]);
+
+				const configuredMdxPlugin = mdxPlugin({
+					remarkPlugins,
+					rehypePlugins,
+					jsx: true,
+					jsxImportSource: 'astro',
+					// Note: disable `.md` support
+					format: 'mdx',
+					mdExtensions: [],
+				});
+
 				updateConfig({
 					vite: {
 						plugins: [
 							{
 								enforce: 'pre',
-								...mdxPlugin({
-									jsx: true,
-									jsxImportSource: 'astro',
-									// Note: disable `.md` support
-									format: 'mdx',
-									mdExtensions: [],
-								}),
+								...configuredMdxPlugin,
+								// Override transform to inject layouts before MDX compilation
+								async transform(this, code, id) {
+									if (!id.endsWith('.mdx')) return;
+
+									const mdxPluginTransform = configuredMdxPlugin.transform?.bind(this);
+									// If user overrides our default YAML parser,
+									// do not attempt to parse the `layout` via gray-matter
+									if (mdxOptions.frontmatterOptions?.parsers) {
+										return mdxPluginTransform?.(code, id);
+									}
+									const frontmatter = getFrontmatter(code, id);
+									if (frontmatter.layout) {
+										const { layout, ...content } = frontmatter;
+										code += `\nexport default async function({ children }) {\nconst Layout = (await import(${JSON.stringify(
+											frontmatter.layout
+										)})).default;\nreturn <Layout content={${JSON.stringify(
+											content
+										)}}>{children}</Layout> }`;
+									}
+									return mdxPluginTransform?.(code, id);
+								},
 							},
-							command === 'dev' && {
+							{
 								name: '@astrojs/mdx',
-								transform(code: string, id: string) {
+								transform(code, id) {
 									if (!id.endsWith('.mdx')) return;
-									// TODO: decline HMR updates until we have a stable approach
-									return `${code}\nif (import.meta.hot) {
+									const [, moduleExports] = parseESM(code);
+
+									// This adds support for injected "page-ssr" scripts in MDX files.
+									// TODO: This should only be happening on page entrypoints, not all imported MDX.
+									// TODO: This code is copy-pasted across all Astro/Vite plugins that deal with page
+									// entrypoints (.astro, .md, .mdx). This should be handled in some centralized place,
+									// or otherwise refactored to not require copy-paste handling logic.
+									code += `\nimport "${'astro:scripts/page-ssr.js'}";`;
+
+									const { fileUrl, fileId } = getFileInfo(id, config);
+									if (!moduleExports.includes('url')) {
+										code += `\nexport const url = ${JSON.stringify(fileUrl)};`;
+									}
+									if (!moduleExports.includes('file')) {
+										code += `\nexport const file = ${JSON.stringify(fileId)};`;
+									}
+
+									if (command === 'dev') {
+										// TODO: decline HMR updates until we have a stable approach
+										code += `\nif (import.meta.hot) {
 											import.meta.hot.decline();
 										}`;
+									}
+									return code;
 								},
 							},
-						],
+						] as VitePlugin[],
 					},
 				});
 			},

package/src/remark-prism.ts

@@ -0,0 +1,60 @@
+// TODO: discuss extracting this file to @astrojs/prism
+import { addAstro } from '@astrojs/prism/internal';
+import Prism from 'prismjs';
+import loadLanguages from 'prismjs/components/index.js';
+import { visit } from 'unist-util-visit';
+
+const languageMap = new Map([['ts', 'typescript']]);
+
+function runHighlighter(lang: string, code: string) {
+	let classLanguage = `language-${lang}`;
+
+	if (lang == null) {
+		lang = 'plaintext';
+	}
+
+	const ensureLoaded = (language: string) => {
+		if (language && !Prism.languages[language]) {
+			loadLanguages([language]);
+		}
+	};
+
+	if (languageMap.has(lang)) {
+		ensureLoaded(languageMap.get(lang)!);
+	} else if (lang === 'astro') {
+		ensureLoaded('typescript');
+		addAstro(Prism);
+	} else {
+		ensureLoaded('markup-templating'); // Prism expects this to exist for a number of other langs
+		ensureLoaded(lang);
+	}
+
+	if (lang && !Prism.languages[lang]) {
+		// eslint-disable-next-line no-console
+		console.warn(`Unable to load the language: ${lang}`);
+	}
+
+	const grammar = Prism.languages[lang];
+	let html = code;
+	if (grammar) {
+		html = Prism.highlight(code, grammar, lang);
+	}
+
+	return { classLanguage, html };
+}
+
+/**  */
+export default function remarkPrism() {
+	return (tree: any) =>
+		visit(tree, 'code', (node: any) => {
+			let { lang, value } = node;
+			node.type = 'html';
+
+			let { html, classLanguage } = runHighlighter(lang, value);
+			let classes = [classLanguage];
+			node.value = `<pre class="${classes.join(
+				' '
+			)}"><code class="${classLanguage}">${html}</code></pre>`;
+			return node;
+		});
+}

package/src/utils.ts

@@ -0,0 +1,60 @@
+import type { AstroConfig, SSRError } from 'astro';
+import matter from 'gray-matter';
+
+function appendForwardSlash(path: string) {
+	return path.endsWith('/') ? path : path + '/';
+}
+
+interface FileInfo {
+	fileId: string;
+	fileUrl: string;
+}
+
+/** @see 'vite-plugin-utils' for source */
+export function getFileInfo(id: string, config: AstroConfig): FileInfo {
+	const sitePathname = appendForwardSlash(
+		config.site ? new URL(config.base, config.site).pathname : config.base
+	);
+
+	// Try to grab the file's actual URL
+	let url: URL | undefined = undefined;
+	try {
+		url = new URL(`file://${id}`);
+	} catch {}
+
+	const fileId = id.split('?')[0];
+	let fileUrl: string;
+	const isPage = fileId.includes('/pages/');
+	if (isPage) {
+		fileUrl = fileId.replace(/^.*?\/pages\//, sitePathname).replace(/(\/index)?\.mdx$/, '');
+	} else if (url && url.pathname.startsWith(config.root.pathname)) {
+		fileUrl = url.pathname.slice(config.root.pathname.length);
+	} else {
+		fileUrl = fileId;
+	}
+
+	if (fileUrl && config.trailingSlash === 'always') {
+		fileUrl = appendForwardSlash(fileUrl);
+	}
+	return { fileId, fileUrl };
+}
+
+/**
+ * Match YAML exception handling from Astro core errors
+ * @see 'astro/src/core/errors.ts'
+ */
+export function getFrontmatter(code: string, id: string) {
+	try {
+		return matter(code).data;
+	} catch (e: any) {
+		if (e.name === 'YAMLException') {
+			const err: SSRError = e;
+			err.id = id;
+			err.loc = { file: e.id, line: e.mark.line + 1, column: e.mark.column };
+			err.message = e.reason;
+			throw err;
+		} else {
+			throw e;
+		}
+	}
+}

package/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),
+		})
+	}
+}

package/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}

package/test/fixtures/mdx-frontmatter/src/layouts/Base.astro

@@ -0,0 +1,18 @@
+---
+const { content = { title: "Didn't work" } } = Astro.props;
+---
+
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta http-equiv="X-UA-Compatible" content="IE=edge">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>{content.title}</title>
+</head>
+<body>
+	<h1>{content.title}</h1>
+	<p data-layout-rendered>Layout rendered!</p>
+	<slot />
+</body>
+</html>

package/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),
+		})
+	}
+}

package/test/fixtures/mdx-frontmatter/src/pages/index.mdx

@@ -0,0 +1,7 @@
+---
+title: 'Using YAML frontmatter'
+layout: '../layouts/Base.astro'
+illThrowIfIDontExist: "Oh no, that's scary!"
+---
+
+{frontmatter.illThrowIfIDontExist}

package/test/fixtures/mdx-get-static-paths/src/content/1.mdx

@@ -0,0 +1,5 @@
+---
+one: hello
+slug: one
+---
+First mdx file

package/test/fixtures/mdx-get-static-paths/src/pages/[slug].astro

@@ -0,0 +1,34 @@
+---
+export const getStaticPaths = async () => {
+	const content = await Astro.glob('../content/*.mdx');
+
+	return content
+    .filter((page) => !page.frontmatter.draft) // skip drafts
+    .map(({ default: MdxContent, frontmatter, url, file }) => {
+        return {
+          params: { slug: frontmatter.slug || "index" },
+          props: {
+            MdxContent,
+						file,
+            frontmatter,
+						url
+          }
+        }
+     })
+}
+
+const { MdxContent, frontmatter, url, file } = Astro.props;
+---
+
+<html>
+	<head>
+		<title>Page</title>
+	</head>
+	<body>
+		<MdxContent />
+
+		<div id="one">{frontmatter.one}</div>
+		<div id="url">{url}</div>
+		<div id="file">{file}</div>
+	</body>
+</html>

package/test/fixtures/mdx-remark-plugins/src/pages/with-gfm.mdx

@@ -0,0 +1,3 @@
+# GitHub-flavored Markdown test
+
+This should auto-gen a link: https://example.com

package/test/fixtures/mdx-remark-plugins/src/pages/with-toc.mdx

@@ -0,0 +1,19 @@
+# TOC test
+
+## Table of contents
+
+## Section 1
+
+Some text!
+
+### Subsection 1
+
+Some subsection test!
+
+### Subsection 2
+
+Oh cool, more text!
+
+## Section 2
+
+And section 2, with a hyperlink to check GFM is preserved: https://handle-me-gfm.com

package/test/fixtures/mdx-syntax-hightlighting/src/pages/index.mdx

@@ -0,0 +1,9 @@
+# Syntax highlighting
+
+```astro
+---
+const handlesAstroSyntax = true
+---
+
+<h1>{handlesAstroSyntax}</h1>
+```

package/test/fixtures/mdx-url-export/src/pages/pages.json.js

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

package/test/fixtures/mdx-url-export/src/pages/test-1.mdx

@@ -0,0 +1 @@
+# I'm a page with a url of "/test-1!"

package/test/fixtures/mdx-url-export/src/pages/test-2.mdx

@@ -0,0 +1 @@
+# I'm a page with a url of "/test-2!"

package/test/fixtures/mdx-url-export/src/pages/with-url-override.mdx

@@ -0,0 +1,3 @@
+export const url = '/AH!'
+
+# I'm a test with a url override!

package/test/mdx-frontmatter.test.js

@@ -0,0 +1,76 @@
+import mdx from '@astrojs/mdx';
+
+import { expect } from 'chai';
+import { parseHTML } from 'linkedom';
+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('renders layout from "layout" frontmatter property', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [mdx()],
+		});
+		await fixture.build();
+
+		const html = await fixture.readFile('/index.html');
+		const { document } = parseHTML(html);
+
+		const layoutParagraph = document.querySelector('[data-layout-rendered]');
+
+		expect(layoutParagraph).to.not.be.null;
+	});
+
+	it('passes frontmatter to layout via "content" prop', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [mdx()],
+		});
+		await fixture.build();
+
+		const html = await fixture.readFile('/index.html');
+		const { document } = parseHTML(html);
+
+		const h1 = document.querySelector('h1');
+
+		expect(h1.textContent).to.equal('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');
+	});
+});

package/test/mdx-get-static-paths.test.js

@@ -0,0 +1,32 @@
+import mdx from '@astrojs/mdx';
+
+import { expect } from 'chai';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+import * as cheerio from 'cheerio';
+
+const FIXTURE_ROOT = new URL('./fixtures/mdx-get-static-paths', import.meta.url);
+
+describe('getStaticPaths', () => {
+	/** @type {import('astro/test/test-utils').Fixture} */
+	let fixture;
+	before(async () => {
+		fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [mdx()],
+		});
+		await fixture.build();
+	});
+
+	it('Provides file and url', async () => {
+		const html = await fixture.readFile('/one/index.html');
+
+		const $ = cheerio.load(html);
+		expect($('p').text()).to.equal('First mdx file');
+		expect($('#one').text()).to.equal('hello', 'Frontmatter included');
+		expect($('#url').text()).to.equal('/src/content/1.mdx', 'url is included');
+		expect($('#file').text()).to.contain(
+			'fixtures/mdx-get-static-paths/src/content/1.mdx',
+			'file is included'
+		);
+	});
+});

package/test/mdx-remark-plugins.test.js

@@ -0,0 +1,62 @@
+import mdx from '@astrojs/mdx';
+
+import { expect } from 'chai';
+import { parseHTML } from 'linkedom';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+import remarkToc from 'remark-toc';
+
+const FIXTURE_ROOT = new URL('./fixtures/mdx-remark-plugins/', import.meta.url);
+
+describe('MDX remark plugins', () => {
+	it('supports custom remark plugins - TOC', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [
+				mdx({
+					remarkPlugins: [remarkToc],
+				}),
+			],
+		});
+		await fixture.build();
+
+		const html = await fixture.readFile('/with-toc/index.html');
+		const { document } = parseHTML(html);
+
+		const tocLink1 = document.querySelector('ul a[href="#section-1"]');
+		expect(tocLink1).to.not.be.null;
+	});
+
+	it('applies GitHub-flavored markdown by default', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [mdx()],
+		});
+		await fixture.build();
+
+		const html = await fixture.readFile('/with-gfm/index.html');
+		const { document } = parseHTML(html);
+
+		const autoGenLink = document.querySelector('a[href="https://example.com"]');
+		expect(autoGenLink).to.not.be.null;
+	});
+
+	it('preserves default GitHub-flavored markdown with "extends"', async () => {
+		const fixture = await loadFixture({
+			root: FIXTURE_ROOT,
+			integrations: [
+				mdx({
+					remarkPlugins: { extends: [remarkToc] },
+				}),
+			],
+		});
+		await fixture.build();
+
+		const html = await fixture.readFile('/with-toc/index.html');
+		const { document } = parseHTML(html);
+
+		const tocLink1 = document.querySelector('ul a[href="#section-1"]');
+		expect(tocLink1).to.not.be.null;
+		const autoGenLink = document.querySelector('a[href="https://handle-me-gfm.com"]');
+		expect(autoGenLink).to.not.be.null;
+	});
+});

package/test/mdx-syntax-highlighting.test.js

@@ -0,0 +1,67 @@
+import mdx from '@astrojs/mdx';
+
+import { expect } from 'chai';
+import { parseHTML } from 'linkedom';
+import { loadFixture } from '../../../astro/test/test-utils.js';
+
+const FIXTURE_ROOT = new URL('./fixtures/mdx-syntax-hightlighting/', import.meta.url);
+
+describe('MDX syntax highlighting', () => {
+	describe('shiki', () => {
+		it('works', async () => {
+			const fixture = await loadFixture({
+				root: FIXTURE_ROOT,
+				markdown: {
+					syntaxHighlight: 'shiki',
+				},
+				integrations: [mdx()],
+			});
+			await fixture.build();
+
+			const html = await fixture.readFile('/index.html');
+			const { document } = parseHTML(html);
+
+			const shikiCodeBlock = document.querySelector('pre.shiki');
+			expect(shikiCodeBlock).to.not.be.null;
+		});
+
+		it('respects markdown.shikiConfig.theme', async () => {
+			const fixture = await loadFixture({
+				root: FIXTURE_ROOT,
+				markdown: {
+					syntaxHighlight: 'shiki',
+					shikiConfig: {
+						theme: 'dracula',
+					},
+				},
+				integrations: [mdx()],
+			});
+			await fixture.build();
+
+			const html = await fixture.readFile('/index.html');
+			const { document } = parseHTML(html);
+
+			const shikiCodeBlock = document.querySelector('pre.shiki.dracula');
+			expect(shikiCodeBlock).to.not.be.null;
+		});
+	});
+
+	describe('prism', () => {
+		it('works', async () => {
+			const fixture = await loadFixture({
+				root: FIXTURE_ROOT,
+				markdown: {
+					syntaxHighlight: 'prism',
+				},
+				integrations: [mdx()],
+			});
+			await fixture.build();
+
+			const html = await fixture.readFile('/index.html');
+			const { document } = parseHTML(html);
+
+			const prismCodeBlock = document.querySelector('pre.language-astro');
+			expect(prismCodeBlock).to.not.be.null;
+		});
+	});
+});