Interactive documentation
Use MDX when a docs page needs live examples, props tables, sandboxes, charts, tabs, or callouts backed by real components.
DocsWhat is MDX?
What is MDX?
MDX is Markdown that can render JSX components. It keeps the writing experience of Markdown, then adds a way to place interactive UI, live examples, charts, callouts, and design-system components inside the same content file.
page.mdx
Markdown + JSXMarkdown prose
Headings, paragraphs, lists, links, blockquotes, and code fences stay readable as text.
JSX components
MDX lets a page render imported UI components next to the written explanation.
A build step
MDX needs tooling that can compile the file into something a web app can render.
Component props
Authors can pass data into embedded components, such as examples, charts, or demos.
Definition
The short answer
MDX is useful when a document should be both readable content and a rendered web page with real components. The tradeoff is that MDX needs build tooling, while ordinary Markdown can be opened, indexed, copied, versioned, and read almost anywhere.
Design-system websites
MDX works well for publishing component guidance because prose and component previews can live in the same source file.
Product education
MDX can turn static docs into richer product pages without abandoning the writing workflow of Markdown.
How it works
What makes MDX different
MDX starts with normal Markdown syntax, then allows JSX imports, exports, expressions, and components. That means an `.mdx` file can describe an idea and render the interface that proves it.
Write normal Markdown for the durable prose and document structure.
Import components from the surrounding web app or docs system.
Place JSX components in the content where a live example should appear.
Compile the MDX file before it can render in the browser.
Example
MDX mixes prose and UI
The Markdown remains readable, but the JSX component only works in an MDX-aware app. That is why MDX is strong for published docs websites and weaker as a universal interchange format.
MDX is less portable than plain Markdown because ordinary Markdown renderers do not understand JSX.
MDX usually belongs in a web project with an MDX-aware build pipeline.
MDX is powerful when the rendered page matters more than plain-text portability.
import { ColorSwatch } from "./ColorSwatch";
export const metadata = {
title: "Brand colors"
};
# Brand colors
Use the primary color for calls to action.
<ColorSwatch name="Primary" value="#10b981" />
Plain Markdown explains the rule. The JSX component
renders the visual example.FAQ
Common MDX questions
Short answers for teams choosing between Markdown, MDX, and portable design documentation.
What is MDX?
MDX is a file format that combines Markdown with JSX, so writers can place UI components directly inside Markdown content.
Is MDX the same as Markdown?
No. MDX includes normal Markdown syntax, but it also supports JSX expressions and components that plain Markdown parsers do not support.
What does MDX stand for?
MDX is commonly understood as Markdown plus JSX. In practice, the name refers to the format and toolchain rather than a strict expanded acronym.
When should you use MDX instead of Markdown?
Use MDX when the page needs interactive components, live examples, or reusable UI. Use plain Markdown when portability, simple editing, and agent-readable text matter most.
Related docs
Keep reading
Definition
What is a design.md?
Learn what a design.md contains, why Markdown is useful for design systems, and how agents use it as implementation context.
Developer guide
Free design.md API and CLI: Extract design.md from a URL
Use hosted keyless extraction with JSON, Markdown, or MDX outputs, plus purchased AI runs and Docker/self-hosted environment keys for private AI enrichment.
Comparison
Markdown vs MDX: Differences and When to Use Each
Compare Markdown and MDX side by side, including portability, syntax, tooling, design docs, and interactive documentation.
Use design.md when the design spec needs to stay portable.
Free design.md turns a public URL into a plain Markdown design system spec that agents can read without a custom MDX renderer.