MDX is Markdown with JSX in the same file. That sounds like a small extension, but it changes what a document can be: a guide can include a live demo, a tab set, or a diagram without moving the whole thing into a component file.

MDX combines words and components

Most of the file is ordinary Markdown:

## A section

This is a paragraph with [a link](https://example.com).

When the prose needs something Markdown does not provide, import a component:

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

<Callout type="tip">
  This is a React component inside the document.
</Callout>

The useful boundary is simple: let the document say what the reader should see; let the component own how it works.

MDX becomes a webpage before you see it

An MDX file is not sent to the browser as-is. A parser turns the Markdown and JSX into a syntax tree. The compiler turns that tree into a JavaScript module. The application then renders the module.

MDX → parser → syntax tree → compiler / bundler → JavaScript → UI

That is why imports have to resolve, component props have to be valid, and a component still has to render accessible HTML.

Use a component when it helps the reader

Use a component when it gives the reader something concrete:

• a <Terminal> block with copyable commands;
• a <Tabs> component for equivalent examples;
• a <Demo> that lets the reader try an idea;
• an <Aside> that separates a useful note from the main thread.

Do not turn every paragraph into JSX. If a normal paragraph does the job, keep it as a normal paragraph. MDX is nicest when the source still reads like a document.

Keep dynamic bits small

MDX can export values and interpolate them into prose:

export const version = '3.0'

This guide targets MDX {version}.

That is handy for small pieces of shared content. Larger logic belongs in a component. Once a reader has to understand an implementation detail to follow the document, the boundary has moved too far into the prose.

Here is what that looks like

Here is a command-line step written as content with one component around the part that benefits from custom presentation:

import { Terminal } from './components/Terminal.jsx'

Run this from the project root:

<Terminal title="Install dependencies">
  npm install
</Terminal>

Then continue to the next step.

The sentence remains easy to edit. The terminal component can handle syntax highlighting, copying, and its visual treatment in one place.

See the difference

<Callout type="tip">Use MDX for docs with components.</Callout>

The same idea takes a different shape in each format. Markdown is for portable writing. HTML is the browser’s document structure. JSX and TSX are for React UI. MDX keeps the writing model and adds components when a page needs them.

A few things can go wrong

Imports still have to work

An import must resolve wherever the MDX file is compiled. A component that exists in one route may not exist in another. Keep imports explicit and close to the top of the file.

Components still need to be accessible

An MDX file does not make a component accessible by itself. Tabs need keyboard behavior. Images and diagrams need useful alternatives. Icon-only controls need names. The output matters more than the fact that the source looked like prose.

Keep layout code out of the article

Prefer a small, named component:

<Comparison before="Markdown" after="MDX" />

over a long block of layout code embedded in the page. The named component gives future authors a vocabulary they can reuse.

Start with Markdown

Start with Markdown. Add a component when the reader needs an interaction, a visual explanation, or a repeated piece of structure. Keep the component’s implementation elsewhere.

That is the appeal of MDX: the source stays close to the shape of an article, but the rendered page can still behave like part of the product.