MDX-Based Documentation Platforms Compared

MDX-Based Documentation Platforms Compared.

MDX as the Default Authoring Format for Developer Documentation

MDX is Markdown plus JSX, and that combination is why it has become the format most developer documentation teams reach for by default. Writers get to keep the plain, familiar syntax of Markdown for headers, paragraphs, and lists, but they can also drop a React component straight into a sentence, with no separate templating system in between. That matters more for developer docs than for almost any other kind of writing, because developer docs aren't just prose. They're playgrounds where someone pastes in an API key and watches a response come back, live code blocks that actually run, product demos, and branded widgets, all sitting inline with the explanatory text instead of living somewhere else.

Documentation isn't only read by people anymore. Tools like Cursor, Claude, and ChatGPT now parse through docs constantly, and a page built from clean, structured components tends to be easier for those systems to pull apart and reason about than one long undifferentiated block of Markdown text. That's a real shift in what "good documentation" even means, and it's one of the throughlines that connects every section of this piece.

Adoption backs this up, though the number is worth reading carefully. Landbase, cited in Fern's March 2026 guide, counted 248 verified companies using MDX for documentation, blogs, and interactive tutorials as of 2025. That's a meaningful number, and it signals MDX has moved well past experimental status. But it's not universal, and the honest framing is "mainstream, not default across the entire industry".

MDX support" is not one fixed thing. Some tools let authors import literally any component and wire up whatever interactive behavior they want. Others hand authors a fixed menu of pre-built pieces, tabs, callouts, and code blocks, and nothing outside that menu. Once a reader understands what full MDX support actually looks like, as opposed to a partial or adjacent version of it, the split between self-hosted frameworks and managed platforms starts to make a lot more sense.

The two-tier structure of the MDX platform market

The market breaks into two tiers (self-hosted open-source frameworks and managed SaaS platforms), and the right choice depends on where a team sits across five dimensions: infrastructure ownership, component extensibility, API reference integration, AI-readiness, and maintenance overhead. In the first tier, the team owns the entire pipeline: build process, hosting, search, analytics, and every dependency update that comes down the line. MDX is native to how these tools work. There's no license fee attached, but there's also no such thing as a free lunch: the cost appears later, in engineering hours spent maintaining the thing.

The second tier is the managed, hosted SaaS model. Here, a vendor runs the CDN, indexes the search, and often handles editorial workflow too, while MDX remains the format authors write in.

This split isn't a marketing distinction dressed up to look meaningful. It changes how a team should actually evaluate options, because the five dimensions that matter most play out very differently depending on which tier a team is standing in.

Teams tend to start in Tier 1, often with Docusaurus or Nextra, because that's where an engineering-led project naturally begins. Then, at some point, the documentation stops being an internal artifact that engineers maintain for other engineers and starts becoming a surface customers actually touch, and that's usually the trigger for a move into Tier 2. Why does that shift happen right around that moment? Because once docs become customer-facing, the cost of an outdated search index or a broken deploy pipeline is no longer just an engineering inconvenience but a support ticket, or worse, a lost sale.

The data shows one clear accelerant behind that migration. GitBook's May 2026 report found that AI agents now account for 51.8% of intentional documentation reads on GitBook-hosted sites, the first time that figure has crossed the halfway mark. When more than half your traffic isn't human, the priorities for a documentation stack start to shift toward things like structured retrieval and agent-specific delivery, which is exactly the kind of infrastructure work managed platforms are built to absorb. The five dimensions are framed briefly here so readers know what each platform section will be evaluated against.

Self-hosted open-source frameworks: what each one offers

Docusaurus is a React and MDX static site generator that deploys cleanly to Netlify, Vercel, or GitHub Pages. What makes it genuinely deep on the MDX side is its "swizzling" system: any default theme component can be overridden, built-in pieces like @theme/Tabs work inside MDX files without pulling in extra npm packages (though each file still needs its own import statement), and live React widgets render right there in the page. Its real strengths are versioning and internationalization, both first-class and both mature, backed by a plugin registry covering analytics, sitemaps, redirects, PWA support, OpenAPI rendering, and blogging. The tradeoff is that all this flexibility has to be operated by someone. Hosting, deployment pipelines, search (usually Algolia or Typesense), dependency updates, and the editorial workflow around all of it fall on the team, a manageable lift for a capable React shop and a compounding headache for anyone else. Docusaurus fits best where contributors are comfortable in Git and where versioning across multiple concurrent releases isn't optional.

It's smaller than Docusaurus by star count (around 8,400 stars) but pulling roughly 200,000 weekly downloads as of 2026, and it's reportedly been growing quickly and taking market share from Docusaurus fast API docs with MDX & components (March 2026) | Fern. The interesting technical bet here is Astro's Islands architecture, which lets components from React, Vue, Svelte, Solid, or plain Astro sit on the same page together, so a team isn't locked into one UI framework. Arcjet's public account of switching to Starlight is a useful data point: the team found Nextra "too inflexible and difficult to customize" and described Starlight as fast, convenient, and equipped with built-in search. The one real limitation is versioning, which is community-maintained rather than built in, and for teams juggling several concurrent release versions, that's often the single deciding factor against it.

Nextra pulls around 800,000 weekly downloads as of 2026 and counts SWR, shadcn/ui, and Vercel's own documentation among its users. Under the hood, MDX 3 support brings React Server Components, Client Components, and incremental static regeneration, plus the ability to render MDX pulled from remote sources (sidebar navigation has to be configured by hand) and full-text search via Pagefind generated at build time.

Fumadocs is the most composable of the group, structured as three separate pieces, a content layer, a core library handling things like search, and a UI library, with official support for Next.js, Tanstack Start, React Router, and Waku, and the option to use only the pieces a project actually needs. It's smaller by GitHub stars (just over 10,000) but is generally positioned as the most customizable and composable Next.js docs framework available. It offers full MDX support with real component extensibility, OpenAPI integration, and a Git-native workflow. The catch, a significant one, is that there's no stable WYSIWYG editor or browser-based content workflow. An experimental in-browser editor exists, but it's dev-only and not ready for production, meaning every contributor needs Git, MDX, and a working Next.js dev environment. For a non-technical writer or product marketer, that's a hard wall. Fumadocs fits teams that are technically sophisticated, want maximum composability, and are fine self-hosting on the free tiers of Vercel or Netlify.

VitePress deserves its own space here because it's the outlier that gets miscategorized constantly. The distinction must be stated: VitePress is not MDX, and embedding Vue components in .md files is not the same operation as embedding JSX. Teams that specifically want MDX with React components should look at Docusaurus or Fumadocs instead. It's free and open-source, worth including here mainly so a team can consciously rule it out (or in) before committing, rather than discovering the JSX gap after the fact. Docusaurus (Meta). The scale signal shows approximately 3M weekly npm downloads and roughly 64,000 GitHub stars as of 2026, with usage by React Native, Jest, Prettier, and Redux Toolkit (docusaurus.io). Astro Starlight. The architecture is a documentation layer on top of Astro (a sidebar generator, content collections, i18n routing, and a heading-to-TOC pipeline), with content in src/content/docs/ as.md or.mdx. The performance argument centers on small bundles, fast pages, and strong Lighthouse scores by default, meaningful if the team has struggled to keep a Docusaurus build under 100KB of JS (API docs with MDX & components (March 2026) | Fern). The cost is covered by an MIT license, completely free, for personal, commercial, and enterprise use. The architecture is Next.js-powered, with file conventions, customizable themes, and MDX 3 support introduced in v3, while v4 fully transitions to the Next.js App Router, discontinues the Pages Router, and supports the latest Metadata API. The positioning nuance is that this is the opinionated, battle-tested Next.js theme path (used when a standard docs layout is a feature, not a limitation), in contrast with Fumadocs' headless/composable approach. For existing Nextra users, v4's App Router transition is a breaking change from earlier versions, so upgrade effort should be planned accordingly. The architecture is a Vite and Vue 3 static-site generator that compiles Markdown into Vue Single-File Components, not JSX-in-Markdown. Adoption stands at approximately 2M weekly npm downloads as of 2026, with usage by Vue.js, Vite, Vitest, Rollup, Pinia, and VueUse. The limitations are no native versioning, a small plugin ecosystem, and a Vue requirement.

Managed MDX platforms: what the SaaS tier adds and at what cost

Fern's whole architecture is built around one idea: the API definition, not the Markdown file, is the source of truth. It connects MDX guides to API reference documentation generated automatically from OpenAPI, AsyncAPI, openRPC, gRPC, or Fern's own definition format. Authors still write in MDX, with prebuilt components like tabs, callouts, cards, and code blocks available out of the box, and custom React components supported for anything more bespoke, an interactive demo or a product-specific widget. What sets Fern apart structurally is that documentation, client SDKs, and a CLI all get generated from that single API definition, with SDKs available in more than nine languages, so docs falling out of sync with what the API actually does gets addressed at the architecture level instead of through manual coordination between teams. On the AI side, every plan, including the free Hobby tier, includes automatic /llms.txt generation and MCP server support. Pricing for the documentation product runs from a free Hobby plan up to a Team plan at $150 a month, with Enterprise available at custom pricing, and features like the API Explorer, web editor, custom CSS and JS, custom React, and AI search gated by plan tier.

A newer category of managed tool is emerging that makes documentation automatically integrated into AI agent workflows. These tools emphasize automatic syncing with product changes, delivery endpoints built specifically for agents rather than browsers, and content that updates in step with the underlying codebase instead of trailing behind it. The capability to test for, when evaluating any platform in this category, is whether it can actually show which agents are reading the docs, what they're asking, and where they're hitting gaps, moving the product from something that just hosts pages to something that actively manages knowledge. That distinction matters because a set of documentation, even well-structured MDX, still becomes a barrier to effective AI deployment if it isn't wired into agent workflows automatically. Mintlify sits in this broader conversation as one platform built around that premise, treating documentation as self-updating infrastructure for both human readers and AI agents rather than a static site that happens to get indexed occasionally, which is part of why component-rich MDX content, not just plain Markdown, has become increasingly relevant to teams building with agents in mind. Pricing for SDK Generation (separate) is Basic at $250/SDK/month, Pro at $600/SDK/month, and Enterprise at custom pricing. The best fit is teams whose primary documentation challenge is keeping API reference and narrative guides synchronized, and who want SDK generation from the same definition. The architecture consists of Git-first MDX, OpenAPI playgrounds, and a CLI and local dev workflow, making it a newer entrant in the managed tier. The pricing model serves as a differentiator, with the Pro plan at $29/month flat, unlimited team members at no extra charge, additional documentation projects at $15/month each, and no AI usage caps. The Pro plan includes AI-powered chat and search, analytics with geographic heatmaps, white labeling, custom domain with SSL, more than 25 MDX components, OpenAPI specification support, automatic llms.txt generation, custom CSS injection, full API access, syntax highlighting for more than 100 languages, password protection, and priority support. The outline should surface, but not resolve, the question of what the trade-off is between a breadth-at-low-cost model and the deeper API integration or enterprise-grade features of the other managed platforms.

How the five decision dimensions land across both tiers

Start with infrastructure ownership, the most concrete of the five. In the open-source tier, owning everything means owning everything: build configuration, hosting, CDN, SSL certificates, search indexing, and every dependency bump falls on the team, full stop. The managed tier flips that, handing infrastructure to the vendor, but that trade brings its own questions. What does a team give up in exchange? Usually some combination of vendor lock-in, exposure to future pricing changes, and reduced control at the infrastructure layer. If a team already deploys comfortably on Vercel or Netlify, the Tier 1 infrastructure cost is genuinely low. But once documentation starts acting as a customer-facing product surface rather than an internal reference, the distraction of running that infrastructure tends to compound rather than stay flat.

Component extensibility splits the field cleanly. Full React extensibility, any component and any import, is available in Docusaurus, Fumadocs, Nextra, and Fern when custom React is enabled. The real question isn't which tool has the most components: the product either actually needs interactive, custom-built demos embedded in the docs, or a solid, standard set of tabs and callouts covers what's needed.

API reference integration is where the open-source tier shows its weakest hand. Docusaurus and Starlight both handle API reference through plugins rather than as a built-in feature, and while Fumadocs and Nextra offer OpenAPI support, it has to be configured by the team rather than working out of the box. Fern's structural bet, generating docs, SDKs, and a CLI from one spec, addresses docs falling out of sync with the API at the architecture level rather than asking a team to catch inconsistencies procedurally, through review and manual checking. Fern's March 2026 analysis takes this drift problem seriously: when MDX content isn't tied directly to API schemas, every parameter change or response format update requires someone to remember to update the prose too, and on a team shipping fast, this small maintenance debt compounds quietly until it becomes a real accuracy problem. So the decision signal here is fairly direct: if API accuracy and SDK generation are what documentation must solve, Fern's architecture was built for that specific job. If API reference is more of a supporting feature next to narrative guides, other platforms are probably adequate.

AI-readiness is the newest of the five dimensions, and also the one still taking shape. In practical terms, in 2026, it means automatic /llms.txt generation, MCP server support, delivery endpoints built for agents rather than browsers, and some way to instrument which agents are actually reading which pages. Every platform discussed here is being pulled toward that bar in one form or another, through a free-tier feature like Fern's automatic /llms.txt generation or through a broader architectural bet on treating docs as living, agent-readable infrastructure rather than a static site. Which of the five dimensions matters most to a given team probably says less about the tools themselves and more about where that team's documentation sits today, and where it's headed next. Multi-framework components (React, Vue, Svelte, Solid on same page) are supported uniquely by Starlight. VitePress is Vue-only (not MDX) and should be filtered out early if JSX/React is a requirement.