Markdown is a formatting syntax that turns plain text into HTML. MDX extends that by letting you use React components inside your markdown files. They look similar, they live in similar places, and they often get confused for each other. This post explains what each format actually does, where each one fits, and how to pick the right one for your project.
What Is MDX?
MDX stands for Markdown + JSX. Files use the .mdx extension and contain a mix of standard markdown syntax and React component imports or JSX expressions.
A compiler (most commonly @mdx-js/mdx or next-mdx-remote) processes .mdx files at build time and turns them into React components. The output is a React component you can render in any React application.
Here's what a simple .mdx file looks like:
import { Chart } from '../components/Chart'
import { Callout } from '../components/Callout'
# Getting Started
This guide walks you through the setup process.
<Callout type="warning">
You need Node 18 or later before continuing.
</Callout>
Here's how usage breaks down across our user base:
<Chart data={usageData} height={300} />
The chart above pulls from live data updated each hour.
The prose is plain markdown. The Callout and Chart are React components imported at the top of the file, just like you would in a .tsx file. The compiler stitches them together.
What Plain Markdown Does
Standard markdown (CommonMark or GitHub Flavored Markdown) renders to HTML through processors like remark, marked, or unified. It supports headings, lists, links, code blocks, tables, and emphasis. That's it.
What makes plain markdown powerful is its portability. A .md file renders correctly on GitHub, in Obsidian, in Notion's import flow, in any static site generator, in VS Code's preview pane, and in any text editor. You write it once and it works in dozens of tools without any build-time dependency.
Plain markdown has no compilation step. You don't need a bundler, a compatible version of React, or any package at all to read or display it. A .md file is just text with a few formatting conventions.
This makes plain markdown the right format for content that travels: blog posts, READMEs, documentation exported to PDF, changelogs, and policy pages. The content exists independently of any particular tech stack.
Where MDX Shines
MDX earns its complexity in situations where static HTML output is genuinely not enough.
Interactive documentation. Libraries that want to ship live code sandboxes alongside their prose (think code that runs in the browser, with editable inputs) use MDX to embed <CodeSandbox> or <LiveEditor> components directly in documentation pages. The prose explains the concept; the component demonstrates it interactively.
Design system documentation. Component libraries often document each component by rendering it live, alongside the code that produces it. MDX lets a documentation author write a sentence, drop in <Button variant="primary">Click me</Button>, and show the actual rendered component without leaving the markdown file.
Data-driven content. If you want to render a chart, a comparison table pulled from an API, or a filterable list as part of a written article, MDX lets you pass props to components inline. The author writes in prose; the component fetches and displays the data.
Editable landing pages. Some teams write marketing copy in MDX so that non-engineers can update headlines and body text without touching a .tsx file directly. The layout components handle structure; the MDX file holds the words. This works well when the content-to-component ratio is high.
Where MDX Gets in the Way
MDX is not free. It carries specific costs worth knowing before you commit to it.
Portability breaks. An .mdx file only renders correctly in environments configured to handle MDX. Open the file on GitHub and you'll see the raw JSX syntax rather than rendered output. Paste it into Notion or Obsidian and the component imports appear as plain text. If your content needs to move between tools, MDX is a liability.
Tooling is fragile. MDX requires a compatible bundler or compiler. Version mismatches between @mdx-js/loader, @mdx-js/react, and your bundler produce cryptic errors that can take hours to debug. Each major version of MDX has changed its API in breaking ways. You take on ongoing maintenance to keep the pipeline working.
Writers hit unfamiliar syntax rules. Markdown authors accustomed to writing .md files need to learn JSX-safe syntax when working in .mdx files. JSX requires self-closing tags (<br /> not <br>), uses className instead of class, and treats curly braces as JavaScript expressions. These rules trip up writers who are not developers. You'll handle support requests.
It's overkill for text-heavy content. Blog posts, changelogs, legal pages, and most documentation articles contain only text, headings, links, and code blocks. None of those require React. Adding MDX to support this kind of content adds build complexity without adding any capability.
The Key Difference in One Sentence
MDX trades portability for interactivity. If you don't need React components embedded in your prose, plain markdown is simpler and works in more places.
That's the whole decision. Count the interactive components your content actually needs. If the answer is zero or close to it, use plain markdown. If your documentation genuinely requires live demos, custom interactive widgets, or data visualizations inside prose, MDX is the right tool.
How md0 Handles Both
md0 CMS reads and writes both .md and .mdx files from your GitHub repository. The visual editor works the same way regardless of file format, so you're not locked into one choice across a collection.
You can mix file formats within a single collection. A docs collection might have mostly .md files for conceptual articles and a handful of .mdx files for pages that embed interactive examples. md0 treats each file according to its extension.
If you're working with plain markdown and want an online editor to draft or format content before it goes into your repo, the md0 markdown editor handles that without any setup.
The format decision belongs to your content, not your CMS. Pick the one that matches what the file actually needs to do.