mdx

Use when working with MDX — custom component mapping, remark/rehype plugins, framework-specific setup (@astrojs/mdx, @next/mdx), and MDX in content collections. Also use for MDX-related configuration and plugin troubleshooting.

Model	Source
sonnet	pack: frontend

Full Reference

┏━ 🔧 mdx ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ MDX — Markdown for the component era ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

MDX

MDX (v3.x) combines Markdown with JSX. Write content in Markdown, embed React/JSX components, use JS expressions, and import/export via ESM.

Item	Value
Core package	@mdx-js/mdx v3.1.1
Pipeline	MDX → mdast (remark) → hast (rehype) → esast (recma) → JS
JSX support	React, Preact, Vue, Solid (via jsxImportSource)
Docs	https://mdxjs.com/docs/

Reference Index

I want to…	File
Set up MDX with Next.js or Astro	reference/setup.md
Map HTML elements to custom components	reference/components.md
Add remark/rehype/recma plugins	reference/plugins.md
Patterns for content collections, frontmatter, layouts	reference/patterns.md

Usage: Read the reference file matching your current task. Load only what you need — don’t ingest all 4 files for a single question.

Key Concepts (Quick Reference)

Concept	What it means
components prop	Map HTML elements (h1, a, code) to custom JSX
remarkPlugins	Transform Markdown AST before HTML conversion
rehypePlugins	Transform HTML AST after Markdown conversion
recmaPlugins	Transform JavaScript AST at the output stage
evaluate()	Compile + run MDX at runtime — only for trusted content
outputFormat: 'function-body'	Use with run() for streaming/edge scenarios
useMDXComponents	Context-based component provider (React, Next.js)

Common Gotchas

Gotcha	Fix
Frontmatter not parsed by @next/mdx	Add remark-frontmatter + remark-mdx-frontmatter
Plugins fail with Turbopack	Pass plugin names as strings, not imports
evaluate() with untrusted input	Never — use a sandboxed render approach instead
format: 'detect' in ProcessorOptions	Banned — only allowed in CompileOptions
Missing mdx-components.tsx in Next.js App Router	Required — App Router will not work without it