MDX

"A format that combines markdown with JSX." You write ordinary Markdown, import a component at the top, and drop it into the prose — <Chart color="#fcb32c" year={year} /> between two paragraphs. It is what a generator reaches for when a page needs an interactive piece inside long-form text, and it is the input format behind Docusaurus's and Astro's component-in-content story (docusaurus, astro-7).

No runtime. "MDX has no runtime, all compilation occurs during the build stage," which is why it sits in this spoke at all: it is a build-time format, not a client dependency, and it composes with islands rather than competing with them.

MIT, mdx-js/mdx, 19,768 stars, 1,180 forks, created December 2017, last push 2026-08-31, 20 open issues. Latest release 3.1.1 (29 August 2025); 3.0.0 landed October 2023.

There is no MDX specification

This page was hunted to close the specification half of the spoke's content-pipeline edge, and the specification does not exist. Checked 2026-09-02: mdxjs.com/spec and mdxjs.com/docs/spec both 404, the mdx-js/mdx repository contains no grammar or spec document, and a code search for "specification" across its Markdown files returns nothing. There is no conformance suite and no version-numbered spec text.

What exists instead is documentation plus a reference compiler. MDX is defined by what @mdx-js/mdx does, and the way to answer a question about the syntax is to run it.

That is worth stating plainly next to CommonMark, which this spoke linked yesterday: Markdown spent ten years being defined by a buggy Perl script until six companies wrote a grammar and 652 conformance examples to end the divergence. MDX, the extension built on top of that fix, is in the pre-CommonMark position — one implementation, no spec, no test corpus anyone else can run. Nothing here says that is a problem in practice; MDX has one dominant implementation and Markdown in 2004 also had one. It is the same starting conditions.

What it is, precisely: CommonMark minus four things, plus three

The markdown half is specified, by inheritance. @mdx-js/mdx depends on remark-parse, remark is built on micromark, and micromark states it is "100% to CommonMark", passing "~650 CommonMark tests and more than 1.2k extra tests confirmed with CM reference parsers." So MDX's prose layer is CommonMark-conformant by construction; the acorn dependency beside it parses the JavaScript half, and remark-mdx joins them.

Added:

• Expressions — JavaScript in braces, evaluated: {Math.PI * 2}
• ESM — import {External} from './place.js' and export const Local = props => <span {...props} />
• JSX components, interleaved with markdown

Removed, and this is the part a generator's users hit:

• Indented code blocks don't work — indentation is reserved for nesting components
• Autolinks are gone, to avoid colliding with JSX like <svg:rect>
• HTML syntax is replaced by JSX (<img> must be <img />)
• HTML comments are replaced by JavaScript comments, {/* comment! */}
• Bare < and { must be escaped as \< and \{

So MDX is not a superset of Markdown, and the losses are not exotic: indented code is how a great many existing documents are written, and a .md file moved to .mdx can break silently on any of the five. Every generator in this spoke that offers MDX as an upgrade path is offering a format that quietly drops CommonMark features.

The autolink removal is the sharpest detail. CommonMark spends 90 of its 652 conformance examples on links — 14% of the suite, second only to emphasis — because that is where Markdown implementations disagreed most. MDX deletes autolinks outright at exactly that spot, because angle brackets belong to JSX now. The place the base spec worked hardest is the place the extension could not keep.

What is packaged

The compiler, three framework contexts, and four build integrations: @mdx-js/mdx (compiler), @mdx-js/react / @mdx-js/preact / @mdx-js/vue, and @mdx-js/rollup (Rollup and Vite), @mdx-js/esbuild, @mdx-js/loader (webpack), @mdx-js/node-loader, plus remark-mdx. The shape is a bundler-plugin story, which is why MDX shows up in JS-toolchain generators and not in Hugo or Jekyll.

Not fetched: the guides section, the playground, and per-generator MDX configuration. The generator-side half of this edge — what Docusaurus or Astro's content collections add on top — is still open.

Related

static-site-generator · docusaurus · astro-7 · astro · islands-architecture · vitepress · dev-tooling-wiki/commonmark