MDX expands authoring power, but adds component-level complexity and build constraints.
What MDX changes
MDX combines Markdown with JSX. That means authors can write ordinary Markdown prose and also embed components. This changes Markdown from a document-only format into a composition format for component-driven interfaces. It is especially popular in design systems, documentation sites, interactive tutorials, and React-based publishing workflows.
The power of MDX is obvious: a document can include live examples, charts, callouts, API playgrounds, custom cards, and reusable UI components. Instead of being limited to Markdown’s small syntax, authors can compose richer pages while keeping prose readable.
The cost is that MDX is no longer portable Markdown in the traditional sense. JSX syntax requires a build system, component imports, runtime assumptions, and a security model. A CommonMark parser cannot render MDX components. A Markdown storage product that accepts .md files should not accidentally treat MDX as ordinary Markdown unless it explicitly supports the combined language.
Markdown syntax and JSX semantics
In MDX, Markdown and JSX coexist. Markdown handles prose structure: headings, paragraphs, lists, links, code blocks. JSX handles component expressions and embedded UI. The parser must understand where Markdown ends and JSX begins. This is a much more complex language boundary than raw HTML in Markdown.
JSX introduces JavaScript expression semantics. Components may receive props. Props may contain strings, expressions, arrays, or objects. Components may depend on imports. This makes MDX closer to source code than plain Markdown. It can be versioned and reviewed like content, but it is also part of the application build.
Because of this, MDX documents should be treated as trusted source in many systems. Allowing arbitrary users to submit MDX is very different from allowing them to submit Markdown. MDX can execute component logic depending on the environment. Security review is mandatory.
Authoring benefits
MDX is excellent when documentation needs interactivity. A design system can show a button component next to its usage guidelines. An API guide can include live request builders. A charting library can render real charts inside docs. A tutorial can include interactive exercises.
MDX also keeps prose close to examples. Instead of writing content in a CMS and wiring examples elsewhere, authors can compose the page in one source file. This improves maintainability for developer-focused documentation.
However, authoring MDX requires more technical skill than authoring Markdown. Writers must understand component names, props, imports, and build errors. A team adopting MDX should provide templates and linting to reduce friction.
Portability concerns
MDX portability is limited because components are application-specific. A component named <Callout> only works if the build environment provides it. Even if another MDX system exists, the component library may differ. This makes MDX powerful for controlled sites and risky for long-term generic storage.
If content may need to move between systems, keep critical meaning in Markdown prose and use components to enhance, not replace, explanation. For example, an interactive demo should be accompanied by textual explanation. If the component fails, the reader should still understand the concept.
MDX also complicates content extraction if important text is hidden inside components that render only on the client. For durable documentation, ensure critical text exists in server-rendered HTML or static output.
MDX versus raw HTML
Raw HTML in Markdown allows authors to insert markup. MDX goes further by allowing component composition. HTML is a markup output language; JSX is a syntax for component trees. This means MDX can express dynamic UI, not just static markup.
That difference is powerful but significant. Sanitizing raw HTML is already non-trivial. Safely evaluating arbitrary JSX is a much larger problem. Public user-generated MDX should be avoided unless the system has a strong sandbox and threat model.
When to choose MDX
Choose MDX when your documentation is part of a web application, your authors are comfortable with component concepts, and the rendered output is controlled by your build system. Do not choose MDX merely because it is trendy. If ordinary Markdown plus a few shortcodes solves the problem, that may be simpler and more portable.
For a Markdown file storage product, MDX should likely be treated as a separate format or future advanced mode, not as default .md behavior. Markdown and MDX overlap, but their operational assumptions differ.
MDX authoring governance
Teams using MDX need governance around component availability and versioning. If a component is renamed or removed, every MDX document using it can break. Component APIs become content APIs. That means design system changes must consider documentation source compatibility.
Provide stable components for common content patterns such as callouts, examples, tabs, and demos. Avoid encouraging authors to import arbitrary application internals. The more controlled the component surface, the more maintainable the MDX corpus becomes.
Static rendering and component boundaries
MDX pages should render important content statically whenever possible. If key explanations appear only after client-side interaction, users with limited JavaScript, export tools, or content extractors may miss them. Components should enhance semantic HTML, not replace it with opaque client-only widgets.
A good MDX page still reads well as a document. Headings, paragraphs, lists, and links should carry the core explanation. Components should demonstrate, summarize, or interact with that explanation. This keeps the page useful for accessibility, export, and future migration. The operational risks are expanded in production Markdown systems.
FAQ
What is MDX?
MDX is a language that combines Markdown prose with JSX component syntax.
Is MDX standard Markdown?
No. MDX extends Markdown with JSX and requires an MDX-aware build pipeline.
Why use MDX?
Use MDX when documentation needs embedded components, live demos, interactive examples, or application-specific UI.
Is MDX portable?
MDX is less portable than CommonMark because it depends on components, imports, and build configuration.
Is MDX safe for user-generated content?
Not by default. Arbitrary MDX can introduce serious security risks and should require sandboxing or trusted author controls.
Related tutorials
- Compare MDX with other dialects in Markdown Dialects Compared.
- Understand AST pipelines in unified and remark Pipelines.
- Review raw HTML boundaries in Markdown Code Spans, Fenced Code Blocks, and Raw HTML.
- Model content structure with Markdown AST with mdast.
- Set product boundaries in Designing Production Markdown Systems.
Continue with Designing Production Markdown Systems.