What Is an MDX CMS? Definition and How It Works

An MDX CMS is a content management system that stores your content as MDX, a format that mixes Markdown with JSX components. You write prose the normal way. Then you drop a <Callout> into the middle of it. The component renders as a real React element. The CMS holds the MDX, and your app compiles it.

That's the short version. The longer version matters, because most platforms that claim MDX support just have a text field. Draftbase stores MDX in typed richText fields and keeps a registry of the components those fields can use. This guide covers what MDX is, what separates a genuine MDX-based CMS from a plain string column, and where the format falls down.

What is an MDX CMS, and how does it work?

An MDX CMS manages content written in MDX and serves it over an API. The flow has three parts.

First, an editor writes MDX in the CMS. Second, the CMS stores it as text and validates the components used against a known list. Third, your app fetches that MDX and compiles it, mapping each component name to real React code.

The third step is where the format earns its keep. A Markdown CMS hands you a string that becomes HTML. An MDX CMS hands you a string that becomes a React tree, with your own components in it.

What "supports MDX" usually means

Nothing, in most cases. Any CMS with a plain-text field can hold MDX. Contentful, Sanity, and Strapi are all named as MDX-friendly in roundups, but none of them models components. You paste MDX into a text area and hope the frontend knows what <Chart> is.

That works until an editor invents a component that doesn't exist. Then the page fails to compile at request time, and nobody finds out until a reader does.

What is MDX, and how is it different from Markdown?

MDX is "a format that combines markdown with JSX," per the official MDX documentation. It's a superset. Every valid Markdown file is a valid MDX file, so migrating up is free. Migrating back is not.

MDX 3 shipped on October 24, 2023. It raised the minimum to Node.js 16, added await inside expressions, and moved parsing to ES2024.

MDX vs Markdown

Markdown gives you headings, lists, links, and code blocks. It renders anywhere: GitHub, a wiki, a plain text editor. Being portable is the whole point of it.

MDX gives you all of that plus three things Markdown can't do:

• Components. <Tabs>, <Callout>, <VideoEmbed>, with props.
• Expressions. {new Date().getFullYear()} runs at compile time.
• Imports and exports. MDX supports ES module syntax directly.

The cost is a compiler. Markdown needs a renderer, which every platform has. MDX needs a build step and a component map, which no platform has by default.

MDX vs HTML

You can already put HTML in Markdown, so why not just do that? Because HTML in Markdown is inert. A <div class="callout"> is styling you copy-paste into forty posts. Change the design and you edit forty files.

An MDX component is one definition. Edit Callout.tsx and every post that uses it updates. The ReadMe comparison makes the same point. Component changes spread on their own. Copy-paste doesn't.

HTML also can't hold state. A <Callout> can be a real React component with a dismiss button.

The two kinds of MDX content management

They look similar from the outside. They fail differently.

Git-based: MDX files in your repo

Tools like Tina, Velite, and Content Collections read .mdx files from your repo. They check each one against a schema. Types get generated at build. Content lives next to code. Version control is free, because it's just Git.

The tradeoff is the deploy. Every typo fix is a commit, a build, and a deploy. For a docs site maintained by five engineers, that's fine. For a marketing team, it's a support ticket.

This group has an upkeep problem worth naming. Contentlayer was the default choice for years. Its last release was June 29, 2023, and its last commit landed September 23, 2023. The maintainer lost sponsorship after Stackbit was acquired by Netlify, and the project stalled. Content Collections picked up the pattern with a Zod-based schema API. Plenty of tutorials still recommend Contentlayer.

API-based: MDX in a database, served over HTTP

Here the MDX lives in a field on a hosted CMS and comes out over a delivery API. Editors don't touch Git. Publishing a fix takes seconds, not a pipeline run.

Draftbase works this way. Entries are typed fields in a database, and richText fields hold raw MDX strings. You fetch them like any other content:

const res = await fetch('https://api.draftbase.co/delivery/entries?templateId=blogPost', {
  headers: { Authorization: `Bearer ${process.env.DRAFTBASE_KEY}` },
});

No vendor tree, no wrapper node format. The field gives you back the same MDX an editor typed.

What makes an MDX CMS more than a text field?

The component registry. That's the whole difference.

A registry is the CMS's list of which components exist, what props each one takes, and what type those props are. With it, the editor can offer a picker instead of a blank box. Checks run at save time, not at render time. And the render boundary has an allowlist, which matters, because MDX from a CMS is remote code executing in your app.

Draftbase registers MDX components with typed props at the org level, and @draftbase/renderer renders them in React and RSC. A component an editor references but that isn't registered gets caught before publish.

Without a registry you have a string column and a promise.

Why do developers pick MDX for content?

Four reasons come up repeatedly, and they're all about the same thing: prose and interface stop being separate systems.

Interactive content stays inline. A pricing table, a live code sandbox, or an API request builder sits in the paragraph where it makes sense. No shortcode syntax, no [embed id=17].

Content is still plain text. Diffs work. Search works. You can grep it. A vendor rich-text JSON tree gives you none of that.

One component library serves docs and app. The <Button> in your product is the <Button> in your changelog.

Types. Component props are typed, so a wrong prop is a build error rather than a broken layout in production.

What are the limitations of an MDX CMS?

Real ones. The official docs list syntax gaps that surprise people. Indented code blocks don't work in MDX. Neither do autolinks. Angle brackets and curly braces need escaping. If you paste Markdown that relied on four-space indentation for a code block, it breaks.

Three more, in rough order of how often they bite:

1. A syntax error kills the page. MDX compiles. Markdown just bends. A stray { in MDX takes the whole document down, and if you compile at request time, it takes it down in production.
2. Non-technical editors struggle. JSX tags, props, nesting, escaping rules. That's a real learning curve for someone who wants to fix a headline. Be honest about this before you pick MDX for a marketing team.
3. It only travels one way. Markdown to MDX is free. MDX back to Markdown means stripping every component and replacing it with something. Your JSX is tied to React.

When is an MDX CMS the wrong choice?

When your editors aren't developers and nobody's building them a visual editor. A marketing team that wants to drag a hero block into place will hate MDX, and no amount of tooling fixes that mismatch. Rich text with a WYSIWYG wins there, and it isn't close.

It's also wrong when every entry has the same shape. If every entry is a product with a name, a price, and three images, you want typed fields, not a prose format. MDX earns its keep on long-form content: docs, changelogs, tutorials, technical blogs.

And it's wrong if your frontend isn't React. MDX compiles to JSX. There are adapters for Vue and Svelte, but you're swimming upstream, and the component ecosystem you'd buy into is React's.

The underused angle: MDX support is mostly a marketing claim

Search "MDX headless CMS" and you'll get roundups naming Contentful, Sanity, and Strapi. Go read their docs. None of them has a component model for MDX.

What they have is a long-text field. That's not nothing, and storing MDX as one portable plain-text string is a genuinely good pattern for avoiding lock-in. But it means the CMS can't check a component, can't offer editors a list of what's available, and can't stop a broken reference from shipping. Every guarantee lives in your frontend, if you built one.

The test is simple. Ask whether the CMS knows the names and prop types of your components. If the answer is no, "MDX support" means "we have strings."

Where to go from here

An MDX CMS is worth it when your content needs components and your editors write code. It's the wrong tool for a marketing site with non-technical authors, and the syntax gaps are sharper than the tutorials admit.

Building docs or a technical blog in React? Draftbase stores MDX in typed fields and checks registered components before publish. Content comes out over a REST or GraphQL delivery API. No deploy needed to fix a typo. The Hobby plan is free with no card, and Startup is $49/mo. On Next.js? Start with the React CMS overview. Or read how schema-driven content modeling shapes the fields your MDX lives in.