MDX — Markdown for the Component Era

Introduction

MDX is an authoring format that combines the simplicity of Markdown with the power of JSX. It allows you to import and render React (or other framework) components directly within Markdown content, making it the standard for interactive documentation, blogs, and content-heavy applications.

What MDX Does

• Parses Markdown with embedded JSX expressions and component imports
• Compiles MDX files into framework components (React, Preact, Vue, Svelte)
• Supports standard Markdown syntax including GFM (tables, task lists, footnotes)
• Allows passing props and data to embedded components at render time
• Integrates with remark and rehype plugin ecosystems for content transformation

Architecture Overview

MDX uses a pipeline: the MDX compiler parses source into an AST using micromark (Markdown) and acorn (JavaScript), then applies remark/rehype plugins for transformations, and finally serializes the AST into a JavaScript module that exports a component function. This pipeline runs at build time, producing static or server-rendered output with no client runtime cost for static content.

Self-Hosting & Configuration

• Add @mdx-js/loader to webpack or use the Vite plugin @mdx-js/rollup
• Configure via mdx options in your bundler (remarkPlugins, rehypePlugins)
• Use next.config.mjs with @next/mdx for Next.js integration
• Set providerImportSource to customize the component provider
• Add TypeScript types with @types/mdx for editor autocompletion

Key Features

• Full interop with any component framework via JSX
• remark/rehype plugin system for syntax extensions and transformations
• Compiles to static output with zero client JS for non-interactive content
• Supports expressions, imports, and exports inside Markdown
• Works with content layers like Contentlayer, Velite, or Fumadocs

Comparison with Similar Tools

• Markdoc — Stripe's Markdoc uses custom tag syntax; MDX uses standard JSX familiar to React developers
• Astro Components — Astro's .astro files mix HTML and JS; MDX focuses specifically on Markdown-first content
• remark-html — remark outputs static HTML; MDX produces interactive component trees
• Docusaurus Markdown — Docusaurus uses MDX under the hood for its documentation features
• reStructuredText — RST is powerful but Python-ecosystem-only; MDX works across JS frameworks

FAQ

Q: Does MDX add runtime overhead? A: No. MDX compiles at build time. Static content ships as plain HTML with zero additional JavaScript.

Q: Can I use MDX with Vue or Svelte? A: Yes. MDX v3 supports multiple JSX runtimes. Configure the jsxImportSource option for your framework.

Q: How do I add syntax highlighting to code blocks? A: Use rehype plugins like rehype-shiki or rehype-prism-plus in your MDX pipeline configuration.

Q: Is MDX compatible with standard Markdown files? A: Yes. Any valid Markdown file is valid MDX. You can rename .md to .mdx and add components incrementally.

Sources

• https://github.com/mdx-js/mdx
• https://mdxjs.com