MDX vs Markdown
MDX is Markdown plus JSX. Reach for Markdown when your content has to render in places you don't control, like GitHub, wikis, or any editor with a built-in renderer. Pick MDX when you want React components, computed values, or interactivity inline with your prose.
At a glance
| Feature | Markdown | MDX |
|---|---|---|
| JSX components | No | Yes |
| Imports / exports | No | Yes |
| JS expressions | No | Yes |
| YAML frontmatter | Yes (with parser) | Yes |
| Standard Markdown syntax | Yes | Yes |
| Renders without a toolchain | Yes (GitHub, wikis, editors) | No |
| Compiles to | HTML | JavaScript module |
| Best for | Static content, READMEs | Interactive docs, blogs, content sites |
When to use Markdown
Stick with Markdown for content that needs to travel. READMEs, wikis, Notion exports, internal team docs: these render natively wherever you put them. It's portable, diffs cleanly, and survives a copy-paste into Slack without mangling. If a future maintainer might open the file in a basic editor and expect it to just work, that's a Markdown file.
If your team's writers don't ship JavaScript, this is almost always the right answer. MDX's flexibility becomes your maintenance burden the first time a <Tabs> component throws in production and the only person who knows the wiring is out for the week.
The shared baseline is CommonMark; most renderers also support GitHub Flavored Markdown for tables, task lists, and strikethrough.
When to use MDX
Pick MDX when prose alone isn't enough. Callouts, tabbed code examples, and conditional rendering against your own data slot in right next to the writing. Next.js, Docusaurus, Astro, and Gatsby all ship first-class MDX support; the format itself is documented at mdxjs.com.
Most Markdown files are valid MDX too. MDX is stricter than CommonMark though, so expect a handful of fixes when migrating: raw < characters in prose, certain HTML blocks, and some indentation patterns that parse fine as Markdown will throw in MDX. The MDX Cheatsheet covers the common gotchas.
Under the hood
Markdown compiles to an HTML string. MDX compiles to a JavaScript module: your content becomes code, with everything that implies. That buys you imports, expressions, and components inline. It also buys you a real security boundary.
Never accept MDX from authors you don't trust. Their content can import anything your bundler can resolve. Markdown is safe to take from anywhere; MDX is safe only from people you'd give commit access. If you're building a CMS where end users author content, this almost certainly means Markdown plus a sanitizer, not MDX.
Decision tree
- Does the file need to render directly on GitHub, GitLab, or a wiki that doesn't run a build? → Markdown.
- Are people you don't fully trust authoring the content? → Markdown. MDX content can import anything in your bundler.
- Do you want React components inline with the prose (callouts, tabs, live demos)? → MDX.
- Do you need computed values, imports, or expressions evaluated at build time? → MDX.
- Otherwise, when in doubt: → Markdown. You can promote it to MDX later without changing a line.
Frequently Asked Questions
What is the difference between MDX and Markdown?
Markdown is a plain-text formatting syntax. MDX extends Markdown with JSX, so you can embed React components, JavaScript expressions, and ES module imports inside your content. Every valid Markdown file is also valid MDX.
Should I use MDX or Markdown?
Use Markdown when content is static and needs to render in many places without a build step: READMEs, GitHub wikis, Notion exports. Use MDX when you need interactive components, dynamic data, or React-driven layouts inside your content.
Can MDX be converted to plain Markdown?
Yes. JSX components, imports, and exports can be stripped to produce plain Markdown. Inline content inside components is preserved; component-only behavior like custom layouts is lost. The MDX to Markdown converter does this in the browser.
Is MDX slower than Markdown?
MDX adds a JSX compilation step, which is slightly slower than parsing plain Markdown. The overhead is negligible at build time and irrelevant at runtime when MDX is statically rendered. For very large content sets, plain Markdown stays marginally faster.
Maintained by Jamdesk · Last reviewed