Skip to main content

MDX

PropertyValue
descriptionMDX
tagsref
rating

Overview​

MDX is an authoring format that combines Markdown with JSX so content can include components directly inside prose.

It matters because it blurs the line between content and application UI, which is powerful in documentation sites and content-driven apps.

What MDX Enables​

MDX lets writers and developers mix ordinary written content with interactive or reusable interface elements.

That usually means a page can contain:

  • normal headings and paragraphs
  • lists and links
  • embedded React components
  • custom callouts, tabs, demos, or data-driven widgets

This makes MDX especially attractive in component-based documentation stacks.

Common Use Cases​

MDX is commonly used for:

  • documentation websites
  • design system docs
  • product guides with interactive examples
  • blog or content pages that need embedded components
  • static site pipelines built around React

That is why it often appears alongside docusaurus, react, jsx, and markup.

MDX vs Markdown​

MDX builds on Markdown, but it is not plain Markdown.

  • Markdown focuses on text structure.
  • MDX adds component syntax and JavaScript-aware parsing rules.

That means an .mdx file may need a build step and framework support that a simple Markdown renderer does not require.

MDX vs JSX​

JSX is primarily UI code.

MDX is primarily document content with optional JSX embedded inside it.

The difference is about authoring intent.

  • JSX usually starts from component logic.
  • MDX usually starts from prose and supplements it with components.

Why MDX Matters​

MDX matters because it gives teams a way to keep content authoring and UI composition in the same system.

That can reduce duplication when docs need reusable patterns such as:

  • product callouts
  • code playgrounds
  • API reference widgets
  • version-aware notices

It can also create more coupling between authors, tooling, and frontend code than plain Markdown would.

Practical Caveats​

MDX is powerful, but it is not always the right default.

  • Non-technical authors may find component syntax intimidating.
  • Build errors can come from both content and code.
  • Framework upgrades can affect content rendering.
  • Rich embedded components can make content harder to port elsewhere.

Teams usually benefit from clear limits on when a page should stay mostly prose versus when it truly needs components.

Frequently Asked Questions​

Is MDX just Markdown with HTML?​

No. MDX is closer to Markdown plus JSX than Markdown plus raw HTML.

Does MDX require React?​

Modern MDX is strongly associated with React ecosystems, although implementation details depend on the toolchain.

Should everything be written in MDX?​

Not necessarily. Plain Markdown is often better when content does not need interactive or reusable components.

Resources​