An MDX formatter for docs with components
MDX lets you write Markdown and drop React components into it, which is why documentation frameworks such as Docusaurus, Next.js docs and Storybook use it. This MDX formatter runs Prettier's mdx parser: Markdown parts get the same treatment as in the Markdown Formatter, while import and export lines and JSX elements are formatted as JavaScript.
Example
import {Callout} from '../components/Callout'
# Installation
<Callout type="warning" title='Heads up'>Node 18 is required.</Callout>
* Run `npm i`
* Start with *npm run dev*import { Callout } from "../components/Callout";
# Installation
<Callout type="warning" title="Heads up">
Node 18 is required.
</Callout>
- Run `npm i`
- Start with _npm run dev_The import gained spaces inside the braces, double quotes and a semicolon. The component's attributes were normalized, and the list and emphasis follow Markdown formatting rules.
Blank lines matter in MDX
MDX decides whether a line is JavaScript, JSX or Markdown partly by blank lines. An import immediately followed by a heading on the next line, with no empty line between, is read as one ES block, and Prettier prints such a block unchanged rather than guessing. If the output looks untouched, add blank lines between imports, headings and components, then format again. The same applies to JSX: leave an empty line before and after a component block so the Markdown inside it is parsed as Markdown.
JSX rules inside MDX
Components in MDX follow JSX rules rather than HTML rules. Use className instead of class, pass numbers and objects in braces (<Chart year={2026} />), and close void elements as <br /> or <img ... />. A parse error in an MDX file very often comes from HTML habits like an unclosed <img>.
When your MDX compiler rejects a formatted file
Formatting and compiling are separate steps, and MDX 2 and later are stricter than plain Markdown. If Docusaurus, Next.js or another MDX 2+ toolchain fails on a file, look for these patterns:
- HTML comments.
<!-- note -->is no longer allowed. Write{/* note */}instead. - A bare less-than sign. In text such as
a < b, the<starts a JSX tag. Escape it as<or wrap it:{'<'}. - Curly braces in prose.
{opens a JavaScript expression, so text like "use {name} here" needs the braces escaped with a backslash or put in inline code. - Angle-bracket autolinks.
<https://example.com>is read as a tag; use[example.com](https://example.com).
Fix these first, then run the formatter so the result is both valid and tidy.
Supported syntax and limits
- ES
import/exportstatements, includingexport const meta = { ... }. - JSX elements and self-closing components with props.
- Markdown lists, tables, headings, code fences and emphasis.
- Prettier's MDX support targets MDX 1 syntax. Some MDX 2/3-only constructs, such as JavaScript expressions in curly braces inside text, may not be formatted or may fail to parse.
Only the Line width option is offered because MDX prose is kept as written (Prettier's proseWrap: "preserve"). To format a component file referenced by your MDX, use the React JSX Formatter. Formatting runs locally in your browser.