What Is MDX? Markdown with React Components

MDX is a format that combines markdown with JSX, letting you embed interactive React components directly in your markdown files. An MDX file (.mdx) is processed by a compiler that turns the markdown into HTML and the JSX into rendered components, producing a single output.

MDX is used primarily in documentation sites, blogs, and content-driven applications where static markdown is not enough but a full React app is too much.

How MDX Works

A regular markdown file:

# Hello World

This is a paragraph.

An MDX file adds component imports and JSX:

import { Chart } from './components/Chart'
import { Callout } from './components/Callout'

# Dashboard Overview

Here's how the numbers look this quarter:

<Chart data={salesData} type="bar" />

<Callout type="info">
  Revenue grew 23% compared to last quarter.
</Callout>

The MDX compiler processes this into a React component. Standard markdown syntax becomes HTML. The JSX elements render as React components. Both coexist in the same file.

MDX vs Regular Markdown

MDX is a superset of markdown. Any valid markdown is valid MDX. MDX adds the ability to import and use JavaScript/JSX.

What You Can Do with MDX

Interactive components:

<Tabs>
  <Tab label="npm">npm install mdtolink</Tab>
  <Tab label="pnpm">pnpm add mdtolink</Tab>
  <Tab label="yarn">yarn add mdtolink</Tab>
</Tabs>

Live code examples:

<CodePlayground language="javascript">
{`
function greet(name) {
  return "Hello, " + name;
}
`}
</CodePlayground>

Data-driven content:

export const features = [
  { name: "CLI", status: "stable" },
  { name: "API", status: "beta" },
]

<FeatureTable data={features} />

Conditional rendering:

{process.env.NODE_ENV === 'development' && (
  <DebugPanel />
)}

Custom layouts:

export default ({ children }) => (
  <BlogLayout author="David">{children}</BlogLayout>
)

# My Blog Post

Content here uses the BlogLayout wrapper.

Where MDX Is Used

MDX is most popular in the React ecosystem. If your site uses React, Vue, Svelte, or another component framework, MDX (or a similar format) lets you blend content and interactivity.

MDX 1 vs MDX 2 vs MDX 3

MDX 2 was a breaking change from MDX 1. Key differences:

• JSX expressions work inline: The answer is {1 + 1}.
• Indented JSX is now allowed
• Better error messages with line numbers
• Faster compilation

If you’re starting fresh, use MDX 3.

When to Use MDX vs Markdown

Use regular markdown when:

• Your content is text, images, and links
• You do not need interactive elements
• You want maximum portability (GitHub, Obsidian, any editor)
• Your team includes non-technical writers

Use MDX when:

• You need interactive components (tabs, toggles, live code)
• You want to embed charts, diagrams, or custom widgets
• Your site is built with React/Next.js/Astro and you want component reuse
• You need data-driven content that pulls from APIs or config files

MDX adds complexity: it requires a build step, a specific compiler, and JavaScript knowledge. For static content, regular markdown is simpler and more portable.

MDX in Astro

Astro supports MDX through the @astrojs/mdx integration:

npx astro add mdx

In Astro, .mdx files in content collections can import and use Astro components:

---
title: "My Post"
---
import Callout from '../../components/Callout.astro'

# My Post

<Callout type="info">
  This callout is an Astro component rendered at build time.
</Callout>

Astro renders MDX at build time, producing static HTML. This gives you the authoring benefits of MDX without shipping JavaScript to the client (unless a component explicitly uses client:load or similar directives).

MDX vs Other Markdown Extensions

Markdoc (created by Stripe) is an alternative to MDX that uses a custom tag syntax instead of JSX. It is simpler but less powerful than MDX.

FAQ

Do I need to know React to use MDX?

For basic use, no. MDX files support standard markdown, so you can write content without any JSX. To create or use custom components, you need basic React/JSX knowledge.

Can I use MDX outside of React projects?

MDX is designed for the JavaScript/React ecosystem. Other frameworks have alternatives: Markdoc for general use, Svelte has svelte-markdown, and Vue has vue-markdown-render. MDX specifically compiles to JSX.

Is MDX harder to learn than markdown?

If you already know markdown and React, MDX is straightforward. The learning curve is in understanding the compiler pipeline (remark/rehype plugins) and knowing how to configure your framework. For writers who do not know React, regular markdown is a better fit.

Can I convert existing markdown files to MDX?

Yes. Rename .md to .mdx and the file works as-is because valid markdown is valid MDX. Then gradually add components where interactive content would help. No need to rewrite existing content.

Try It Out

Write standard markdown in the MDtoLink editor and publish it to a shareable URL. For MDX-specific features, use your framework’s dev server to preview components.

For the markdown syntax reference, see the markdown cheat sheet. For the base specification, see What Is CommonMark?.