MDX vs Markdoc for Docs Content

Plain Markdown runs out quickly in documentation. Writers need tabs for per-language samples, callouts, cards, embedded diagrams and version badges, and every docs framework offers a way to put components into prose. The two serious options are MDX, which turns Markdown into JavaScript and lets you write JSX inline, and Markdoc, Stripe's format, which adds a small tag syntax ({% tabs %}) that is parsed, validated against a schema and rendered — but never executed.

The choice shapes three things for years: how often contributors break the build, what a malicious or careless pull request can do, and how long every build takes. This guide compares them on a real docs corpus in Astro and Starlight, where both are first-class. It belongs to Docs Frameworks: Docusaurus, Starlight and VitePress.

Prerequisites

• An Astro or Starlight project (@astrojs/mdx and @astrojs/markdoc integrations installed), or a Docusaurus site if you are evaluating MDX alone.
• A list of the components your writers actually use — usually fewer than ten.
• Build timing in CI, so you can measure the difference on your own corpus rather than trusting ours.

How Each Format Works

MDX compiles each file through remark and rehype into a JavaScript module. Components are imported at the top of the file and used as JSX. Curly braces evaluate JavaScript expressions. The result is enormously flexible — a page can compute a table from imported data — and any syntax error in the JSX is a compile error for the whole page.

Markdoc parses each file into an abstract syntax tree, validates tags and attributes against a schema you define (tabs requires items, callout accepts type of note|warning), transforms the tree, then renders it with your components. Tags cannot contain expressions beyond variables and functions you explicitly register, so content is data, not code.

<!-- MDX -->
import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="npm">`npm i acme`</TabItem>
  <TabItem label="pnpm">`pnpm add acme`</TabItem>
</Tabs>

<!-- Markdoc -->
{% tabs %}
{% tabitem label="npm" %}`npm i acme`{% /tabitem %}
{% tabitem label="pnpm" %}`pnpm add acme`{% /tabitem %}
{% /tabs %}

Authoring Errors in Practice

The format decision is mostly felt through error messages. Over one quarter, a 1,200-page docs repository with 38 regular contributors logged every failed build:

Two patterns stand out. First, most MDX failures had nothing to do with components: a writer typed latency < 200ms or pasted JSON outside a code fence, and the JSX parser rejected it. Second, Markdoc's schema caught mistakes MDX let through silently — an attribute typo like lable="npm" renders an unlabeled tab in MDX but fails validation in Markdoc with a message naming the file, line and attribute.

Build Speed

The same 1,200 pages were built three ways in Astro 5 on a GitHub Actions runner, timed with hyperfine over five runs:

MDX's extra fifteen seconds comes from compiling each page to a JavaScript module and bundling it. On a 10,000-page site that difference scales to minutes, which matters for preview deploys; see Astro vs Eleventy Build Times at 10,000 Pages for the scaling behaviour.

Security and Review

An MDX file is a program. It can import fs from 'node:fs' and read environment variables at build time, and a build that has deploy credentials in its environment will happily run it. For internal docs written by employees that is a manageable risk; for an open-source repository accepting pull requests from strangers, it means every content pull request needs code review, and preview builds of forks must run without secrets — the setup in Securing Deploy Credentials with GitHub OIDC helps here.

Markdoc content cannot import anything. Tags map only to components you registered, and functions available in content are only those you declared. A malicious Markdoc file can produce ugly output, but it cannot exfiltrate secrets.

The review burden follows directly. On the repository measured above, content pull requests that touched only .mdoc files were approved by a writer alone, with a median review time of 3 hours. Pull requests touching .mdx files required an engineer's approval under the repository's CODEOWNERS rules, and their median review time was 19 hours, largely spent waiting for an engineer to become available. Routing by file extension turned the security boundary into a workflow boundary: writers could move quickly on the content that could not hurt anything, and engineering attention went to the small set of files that could.

A schema also documents itself. The Markdoc config lists every tag, every attribute, its type and whether it is required, and that list can be rendered into a contributor guide automatically. With MDX, the equivalent documentation is whatever the component authors remembered to write, and the only complete reference is the component source.

Choosing and Mixing

Use this split, which several large docs teams have converged on:

• Markdoc for the bulk of pages edited by writers, support staff and outside contributors. Define a schema of eight to twelve tags and treat it as the content API.
• MDX for the handful of engineer-owned pages that genuinely need code: an interactive configuration generator, a page computed from imported data.
• Plain Markdown wherever no component is needed — which, in most docs repositories, is the majority of files.

Starlight and Astro allow all three in one content collection, so the split can be per file. Pair it with a lint rule that fails CI when a .mdx file has no import or JSX, forcing it back to .md or .mdoc. The same "smallest capable format" idea shows up in Shortcodes vs Components for Docs Authors.

Pitfalls & Rollback

• Converting everything to MDX "for consistency". It imports MDX's error modes into files that never needed components. Keep plain pages plain.
• An unbounded Markdoc schema. Adding a tag for every one-off layout recreates MDX's flexibility with worse ergonomics. Review new tags like API changes.
• Forgetting editor support. Install the Markdoc language server or VS Code extension so writers see schema errors as they type, not only in CI.
• Migrating in one pass. Convert the highest-traffic, most-edited pages first and measure failed-build rates before committing to a full conversion.
• Duplicated components. Markdoc tags and MDX components should render through the same underlying Astro component, so a design change lands once and both formats stay visually identical.
• Rollback: formats coexist per file, so converting back is a per-file rename plus rewriting tag syntax. Keep the conversion script reversible and the change set small enough to revert.

Conclusion

MDX gives engineers maximum power and gives writers a JavaScript compiler's error messages. Markdoc gives writers a small, validated vocabulary and gives security reviewers content that cannot execute. On a 1,200-page, 38-contributor repository, Markdoc cut failed builds per hundred edits from 4.1 to 0.9 and built 30% faster. Default to plain Markdown, use Markdoc when writers need components, and reserve MDX for the few pages where content genuinely has to be code.

FAQ

What is the core difference between MDX and Markdoc?

MDX compiles Markdown into JavaScript, so any JSX expression or import is executable code. Markdoc parses Markdown with a fixed tag syntax into a data tree that is validated against a schema and then rendered, so content cannot run arbitrary code.

Which is faster to build?

Markdoc, in our measurements. On 1,200 pages in Astro, Markdoc content built in 34 seconds against 49 seconds for the same content as MDX, because Markdoc skips the JavaScript compilation step for each file.

Can I use both in one site?

Yes. Astro and Starlight accept Markdown, MDX and Markdoc side by side. A common split is Markdoc for contributor-edited pages and MDX for a few engineer-owned pages that need custom interactive components.

Is MDX unsafe for open-source docs?

It is a risk to manage rather than a reason to avoid it. An MDX file can import and execute code at build time, so pull requests from outside contributors need the same review as code changes. Markdoc removes that class of risk.

Related

• Parent: Docs Frameworks: Docusaurus, Starlight and VitePress — where content format fits the framework choice.
• Content Collections vs Eleventy Data Cascade — schema validation for front matter.
• Best SSG for Technical Writers Without Coding Experience — authoring ergonomics across generators.
• Editorial Checks with Vale in CI — linting prose alongside markup.
• Migrating from MkDocs to Starlight — where MDX was needed only for tabs.