What is MDX?

You know Markdown — the simple syntax where # makes a heading, text makes bold, and you can write content without touching HTML.

And you know React — components, props, state, the whole deal.

MDX is what happens when you smash them together. You get a .mdx file where you can write normal Markdown AND drop in React components wherever you want.

Here's what that looks like:

Hello, World!
─────────────

This is regular Markdown, but below is a React component:

[Welcome Component Rendered Here]

And we're back to regular Markdown again.

That's it. That's the core idea. Markdown for content, React for interactivity — in the same file.

How MDX Works (The Short Version)

Your .mdx file doesn't run directly in the browser. Here's what happens:

1. You write a .mdx file with Markdown + components
2. The compiler converts it into a React component (plain JavaScript)
3. Your framework (Next.js, Docusaurus, etc.) renders that component like any other

Think of it like this: MDX is a build-time format. By the time users see your page, it's already been compiled into regular React.

Who Uses MDX?

Pretty much everyone building documentation or content-heavy sites:

• Next.js docs — the official documentation uses MDX
• React docs — interactive examples powered by MDX components
• Vercel, Stripe, Tailwind — their docs are MDX-based
• Docusaurus — Meta's doc framework is built around MDX
• Hundreds of developer blogs — because it's just nicer to write in

If you're building a docs site, a blog with code examples, or any content that needs interactivity — MDX is probably what you want.

MDX vs Regular Markdown

The rule is simple: if your content is purely text and images, regular Markdown is fine. The moment you need anything interactive or reusable, switch to MDX.

Quick History

• 2018 — John Otander creates MDX v1. First time you could write JSX inside Markdown.
• 2021 — MDX v2 arrives with a complete rewrite. Better error messages, JS expressions support, stricter parsing.
• 2023 — MDX v3. ES modules, better performance, modern tooling.
• Today — It's the standard for docs sites. Every major framework supports it.

What You'll Learn in This Tutorial

This tutorial covers everything from zero to production:

1. Setup — Install MDX in Next.js, Vite, or Docusaurus
2. Basics — All the Markdown features (headings, lists, tables, code blocks)
3. Components — Import and use React components in your content
4. Advanced — Plugins, layouts, syntax highlighting, performance
5. Real Examples — Build an actual docs site, blog, or portfolio

Let's get started. Next up: Why Use MDX?

Common Use Cases for MDX

MDX shines in specific scenarios where traditional Markdown falls short:

Technical Documentation: Companies like Vercel, Stripe, and Tailwind use MDX for their docs. They embed interactive code playgrounds, live component previews, and tabbed code examples directly in the documentation. Writers focus on content while developers build reusable components.

Educational Content: Online courses and tutorials benefit enormously from MDX. Instead of static code blocks, you can embed runnable code editors, interactive quizzes, step-by-step animations, and collapsible solution panels — all within the same Markdown-like authoring experience.

Design Systems: Component libraries use MDX to document their components with live, interactive examples. Each component's documentation page includes working demos that readers can modify in real-time, props tables generated from TypeScript types, and usage guidelines.

Blog Posts with Data: Technical blog posts often need charts, diagrams, or interactive visualizations. With MDX, you can import a chart component and pass data directly in your blog post without building a custom page template.

How MDX Works Under the Hood

Understanding the compilation pipeline helps you debug issues and write better MDX:

1. Parsing: The MDX compiler first parses your file, separating Markdown content from JSX expressions and import statements.
2. AST Generation: It builds an Abstract Syntax Tree (AST) combining the mdast (Markdown AST) and esast (JavaScript AST) formats.
3. Plugin Processing: Remark plugins transform the Markdown AST (add table of contents, process math), and rehype plugins transform the HTML AST (syntax highlighting, image optimization).
4. Code Generation: The final AST is compiled into a JavaScript module that exports a React component. When rendered, this component produces the combined output of your Markdown content and JSX components.

This pipeline means MDX files are ultimately JavaScript modules — they can export variables, import dependencies, and participate in your bundler's module graph just like any other JS file.

MDX Ecosystem and Tooling

The MDX ecosystem includes several important tools:

• @mdx-js/mdx: The core compiler that transforms MDX to JavaScript
• @mdx-js/loader: Webpack loader for bundling MDX files
• remark-gfm: Plugin for GitHub Flavored Markdown (tables, strikethrough, task lists)
• rehype-highlight: Adds syntax highlighting to code blocks
• next-mdx-remote: Loads MDX content from external sources in Next.js (CMS, database, file system)