Performance Comparison

Performance in documentation tooling splits into two questions that are usually confused: how long the build takes, and how much the reader has to download. The four frameworks answer both in a similar direction, because they all produce static sites, but they arrive there by very different routes, and the routes have different consequences for a team that maintains documentation for years.

Before comparing anything, one caveat governs the whole page. The published numbers you will find for these tools were produced by different people, on different hardware, with different content, measuring different things, and they are not comparable with one another. Some measure a cold build of a site with hundreds of pages, some measure a warm rebuild after a single file changed, some measure the total size of the output directory, and some measure the JavaScript a reader downloads on the first page load. A figure from one of those measurements tells you almost nothing about the same figure in another tool. The only honest way to compare is to run the same experiment on your own content, which is why the last section of this page explains how to do that.

Build model

The first structural difference is how the site is produced.

MkDocs is a single Python process that walks the content directory, renders each file, writes it out, and copies the static assets. There is no bundler, no module graph, and no dependency analysis. The work is linear in the number of pages, and the constant factors are small because nothing is being transformed by a JavaScript toolchain. For a documentation set of a few hundred pages, a full build is a short job.

VitePress and Astro both sit on Vite. Vite keeps a module graph, tracks which files changed, and can rebuild only the parts of the output that depend on what changed. In practice this shows up most clearly in the development server rather than in the production build: the server starts in a moment and updates the page you are editing without a full browser reload, because the changed module is transformed and re-rendered on demand. Astro applies the same idea to islands, so a change to a single component re-renders the pages that use it.

Docusaurus is the outlier. Its production build compiles a React application, which means the tool has to do dependency resolution, transpilation, and code splitting across the whole site before it can emit HTML. That is more machinery than the other three need, and it exists because Docusaurus’s output is a client-side routed application rather than a set of independent pages.

FrameworkBuild modelWhat dominates the build
MkDocsLinear Python render and copyPage count
VitePressVite build with per-page server-rendered chunksPage count and Vue dependencies
Astro / StarlightVite build with per-page islandsPage count and integration count
DocusaurusApplication-wide build of a React siteThe whole dependency graph

The development loop

For a documentation project, the feedback loop matters more than the nightly build, because documentation is written in many small increments and the writer is looking at the result after every save.

MkDocs’ development server watches the content directory and rebuilds the affected pages. It is a straightforward reload rather than a hot module replacement, but for text-heavy editing it is entirely adequate, and the server starts almost immediately.

VitePress and Astro give the strongest loop of the four, because a single file change is transformed and swapped into a running page without reloading the browser. For a site that is mostly prose this is a pleasant difference rather than a transformative one; for a site with many components it becomes the reason to prefer them.

Docusaurus’ development server is the slowest to start and the least incremental of the group, because the application has to be compiled before it can be served.

What the reader downloads

This is where the differences are largest and where the choice has the most visible effect.

MkDocs produces HTML, a stylesheet, and at most a small search script. There is no framework runtime in the output at all.

Astro with Starlight produces HTML, a stylesheet, and a search script built from a static index. Interactive components are opt-in islands, each loaded only on the pages that use it, so a documentation site built this way can ship close to nothing in the way of JavaScript.

VitePress produces HTML with no framework code on pages that contain only prose. Vue is loaded on the pages that use a component, as a separate chunk, and those pages are a minority in a typical documentation set.

Docusaurus produces a React application. Every page carries the framework runtime and the hydration code for the interactive parts of the layout, which makes it the heaviest of the four in bytes transferred and in main-thread work before a page becomes usable.

Measuring your own project

If a performance decision matters enough to argue about, run the experiment rather than argue. Take a representative copy of your own content — at least a few hundred pages, with the code blocks and images your real pages have — and measure four things on the same machine, on the same day, with each tool configured the way you would actually configure it.

First, a cold build: clear every cache and time the full build from an empty output directory. Second, a warm rebuild: change one file, save, and time how long until the preview reflects it. Third, the output size: measure the total size of the generated directory, and separately the bytes transferred to load one typical page with the browser cache disabled. Fourth, the time until a page is usable on a throttled connection, which is the number a reader actually experiences.

Then change one variable and repeat. Replacing the theme with the default one, turning search off, or removing the few interactive components will show you where the cost actually is, and the answer is frequently not where you assumed. Recording the numbers in the repository next to the documentation config also means the next person to raise the question can see the answer instead of re-running the experiment.

What the comparison says

Three practical consequences come out of this. If the reader experience is the priority and the site is mostly prose, the JavaScript frameworks all behave acceptably and the deciding factor should be elsewhere. If bytes matter, the ranking is clear and it favours the tools that do not send a runtime. If the authoring loop matters most, the Vite-based tools win. If the build has to be cheap enough to run on every pull request against a very large site, the simpler the build pipeline the better, and that is an argument for the tools that do less.

None of these conclusions requires a benchmark table, which is the practical reason to distrust benchmark tables for this decision.

Found an issue with this content?

Tell us what could be improved.