Feature Comparison

Two documentation frameworks can offer the same headline features and still be entirely different tools, because the headline features are the easy part. The differences that matter in daily use are in the authoring format, in how the site is extended, and in the handful of content problems — versions, languages, search, code — that every documentation set eventually runs into. This page compares the four tools along those axes.

Authoring format

VitePress, MkDocs, and Starlight are Markdown-first tools. A document is a Markdown file, and anything beyond Markdown is a deliberate, visible extension: a container in VitePress, an admonition in MkDocs, an aside in Starlight. Docusaurus is different, because its content format is MDX, which is Markdown with JSX expressions allowed inside it. That single difference propagates: in Docusaurus a document is a React component tree, so you can import a chart at the top of a file and render it inline, and the trade-off is that a stray brace or a stray angle bracket becomes a build error.

CapabilityVitePressDocusaurusAstro StarlightMkDocs Material
Content formatMarkdownMDXMarkdown and MDXMarkdown
Custom componentsVue componentsReact componentsAny framework the project installsPython plugins, Jinja templates
Interactive elementsVue components in the pageReact components inlineIslands, any frameworkNeeds a plugin or an embedded script
Call-outsCustom containersAdmonitions and MDX componentsAsides and GitHub-flavored alertsAdmonition extension
TabsCode groupsTabs componentTabs componentTabbed extension
DiagramsMermaid, Shiki highlightingMermaid themeMermaid, native diagram supportMermaid extension
Syntax highlightingShikiPrismShikiPygments or the extension family

Extending the site

Each tool offers several extension points of different shapes, and the shape is what determines the cost of a given task.

In VitePress, the theme is a Vue application. You can override any part of it by adding files under the theme directory, which is ordinary Vue component authoring, and you can add new components to Markdown pages.

In Docusaurus, the theme is a React component library. Replacing a component is a documented operation with a command behind it, and plugins are Node packages that hook into the build and can inject components into the rendered output.

In Starlight, the theme is built on Astro, and the extension model is Astro’s own: components written in any framework the project has installed, plus a configuration file that registers them with the documentation. The result is that a company that already has React components can reuse them directly, without the documentation site needing to become a React application.

In MkDocs, the theme is a set of Jinja templates and the behaviour comes from Python plugins. The consequence is that MkDocs can do almost anything, but a new behaviour is a Python program rather than a component you drop into a page.

All four support the hosted DocSearch service, which is the usual answer for a public documentation site with many pages. Beyond that they differ.

VitePress ships a local search that is built during the build and queried in the browser. Docusaurus delegates to a search plugin, with the hosted service as the first-party option and community plugins available for local search. Starlight uses a static search index generated after the build, which keeps the index in step with the site and needs no service. MkDocs Material ships a local search plugin that builds its index during the build, supports multiple languages, and can be configured to index headings only or titles only when a site is very large.

The practical difference is not quality but dependencies. A local index means no hosted service, no API key, no per-query cost, and no third party in the request path — which matters for an internal site on a private network. A hosted index generally handles typo tolerance and ranking more aggressively, which matters more as a site grows.

Internationalisation

All four can publish more than one language, and all four do it by keeping parallel trees of content.

Docusaurus has the most complete built-in support, with a locale-aware configuration, a translation workflow, and localized routes. VitePress configures locales in the site configuration and nests each language’s pages in a subdirectory. Starlight follows Astro’s own internationalisation configuration, which covers routing between locales as well as the translated content. MkDocs Material handles multiple languages through separate builds with a per-language configuration, which is less integrated but perfectly workable.

The question to ask is not which has the most features but how the translations are produced. Docusaurus and VitePress can pull the translated strings out of the interface as well as the pages; the others generally require the translated interface to be handled separately.

Versioning

Docusaurus is the only one of the four with first-class documentation versioning. It can snapshot the entire documentation set at a release, keep the snapshots side by side, provide a version switcher, and archive old versions. That is a real feature rather than a convention, and it is the single largest capability difference between these tools.

The other three treat versioning as a structural problem you solve with directories. You keep one folder per released version, you give each one its own navigation entry, and you write the version switcher yourself, usually with a small script that reads the list of versions from the build output. That is more work but not much, and it gives complete control over how much of each old version is kept.

Deployment

All four produce a directory of static files, so all four deploy to any static host, object store, or CDN, and all four can be published by a CI job that runs on every merge.

Docusaurus additionally has a built-in command for publishing to a GitHub Pages branch. VitePress, Starlight, and MkDocs assume you will run the build yourself and copy the output, which in a CI job is a two-line step for all three.

What the comparison says

Read across the table rather than down a column, and a pattern emerges. The differences between these tools are not gaps in any of them; they are differences in what each one optimises for. VitePress optimises the authoring loop, Docusaurus optimises the surrounding application, Starlight optimises the output, and MkDocs optimises the setup cost. The features you will notice on day one are close to identical, which is why the choice should be made on the axes that will still matter in a year: who writes the content, what the site must contain besides documentation, and how much of it needs to change over time.

Found an issue with this content?

Tell us what could be improved.