What MDX Adds to Markdown

Markdown earned its place as the default format for developer documentation by keeping syntax simple while making commands readable. It was so popular that chat applications like Slack and WhatsApp adopted its conventions, and document tools like Dropbox Paper and Notion followed suit. GitHub went a step further by rendering HTML elements—links and images, for instance—directly in README files.

Markdown is not broken, but it does have limits. The MDX project (Markdown Extended) pushes past them by allowing JavaScript and React components to live inside Markdown documents. That capability, combined with standard Markdown syntax and JSX, turns static text into interactive content.

Real-world usage shows just how flexible MDX is:

  • Demoboard from Frontend Armory uses MDX on its education playground to produce pages that are both runnable demos and documentation.
  • Brent Jackson combines MDX with Styled System for a site-building approach where each page is written in MDX and styled via Styled System's blocks. The project is in development; details are on its website.
  • mdx-deck and Spectacle let you place live demos directly inside presentation decks, dropping the need to switch screens during talks.
  • Tools for documenting component libraries in MDX include MDX Go, ok-mdx, and Docz, allowing components to be dropped directly into documentation files.
  • Zeit Now and Prisma docs use MDX to write their content.

For a React-based blog, MDX eliminates the need to build custom component pages (or plugins) for anything Markdown can't express. An example is the author's blog, which relies on MDX to embed Playground, a React component that shows editable HTML/CSS/JavaScript snippets. Doing so avoids loading third-party scripts for demos. Similarly, MDX simplifies embedding iFrames from services like YouTube, Vimeo, and Giphy.

Writing with .mdx Files

Files written in MDX use the .mdx extension. The content mixes familiar Markdown syntax with JSX, making interactive visualizations and custom styling a first-class part of the document:

import InteractiveChart from "../path/interactive-chart";


# Hello - I'm a Markdown heading


This is just markdown text


<InteractiveChart />

An example from the author's portfolio illustrates the pairing:

MDX files are also composable. Just like React components, documents can be split into smaller pieces and reused across pages, rendering together at load time:

import Header from "./path/Header.mdx"
import Footer from "./path/Footer.mdx"

<Header />

# Here goes the actual content.

Some random content goes [here](link text)

<Footer />

Adding MDX to a React Project

MDX ships with integration plugins for the most common React frameworks, including Gatsby and Next.

In a create-react-app project, a Babel Macro provides the path in—it simply gets imported into the app:

import { importMDX } from './mdx.macro'
 
const MyDocument = React.lazy(() => importMDX('./my-document.mdx'))
 
ReactDOM.render(
  <React.Suspense fallback={<div>Loading...</div>}>
    <MyDocument />
  </React.Suspense>,
  document.getElementById('root')
);

A live playground is available for trying MDX without setting up a project.

For Vue, MDX contributors have posted an experimental example on GitHub. That support is in Alpha and not production-ready.

Editor Tooling and Plugins

Syntax highlighting and autocomplete support has grown for MDX in VS Code, Vim, and Sublime Text. These tools still have rough edges—mainly because they cannot always tell whether the cursor is inside JavaScript or Markdown, making navigation tricky.

A more fundamental advantage: MDX is part of the unified ecosystem, which also hosts the remark and rehype plugin systems. That means MDX inherits a large ecosystem of existing plugins, like remark-images and remark-redact, without reinventing APIs. Adding a plugin is a matter of wiring it into the corresponding loader. For custom needs, MDX provides a guide for writing new plugins.

MDX is young, but its adoption across blogging, data visualization, live demos, and presentations suggests it has moved beyond a novelty into a practical tool for interactive content.