Comparing Docs Framework Build Times

Ready-made documentation frameworks — Docusaurus, Starlight and VitePress — save months of theme work, and choosing between them is usually a question of ecosystem, authoring format and features. Build time rarely features in the comparison until the site is large, at which point it becomes the thing everyone complains about: preview deploys that take ten minutes, writers who stop waiting for them, CI bills that grow with every guide.

This guide benchmarks the three frameworks on the same documentation corpus at three sizes, measures cold and warm builds, peak memory and output size, and explains what drives each framework's numbers and which settings help. It is part of Docs Frameworks: Docusaurus, Starlight and VitePress, and uses the method from How to Benchmark Hugo vs Astro Build Speeds.

Prerequisites and Method

• Corpus: a real product documentation set of 2,000 Markdown pages (1.4 million words, 11,800 code blocks, 640 images), converted to each framework's conventions with a script. Subsets of 500 and a synthetic 5,000-page version (duplicated with varied slugs) were used for scaling.
• Versions: Docusaurus 3.6 (webpack and the faster Rspack option), Starlight 0.29 on Astro 4.16, VitePress 1.5.
• Features enabled in all three: syntax highlighting (Prism in Docusaurus, Shiki in the others), sidebar generated from folders, local search index (Docusaurus with @easyops-cn/docusaurus-search-local, Starlight with its built-in Pagefind, VitePress with its built-in MiniSearch), no image optimization.
• Machine: GitHub Actions ubuntu-latest larger runner, 8 vCPU, 32 GB RAM; timings are medians of five hyperfine runs, cold builds with all caches removed, warm builds with framework caches present and no content changes.

hyperfine --runs 5 --prepare 'rm -rf .docusaurus build node_modules/.cache' 'npx docusaurus build'
hyperfine --runs 5 --prepare 'rm -rf dist node_modules/.astro' 'npx astro build'
hyperfine --runs 5 --prepare 'rm -rf .vitepress/dist .vitepress/cache' 'npx vitepress build docs'

Results at 2,000 Pages

What Drives Each Number

Docusaurus compiles every page's MDX into a React component module, bundles all of them with webpack (or Rspack) into client and server bundles, then server-renders every route with React. Bundling thousands of page modules is the dominant cost, and it is also why memory is high. The future.experimental_faster option switches to Rspack, SWC and Lightning CSS, which halved the cold build on this corpus. Docusaurus also ships the most client JavaScript per page, because it is a React single-page app after the first load.

Starlight uses Astro's static rendering: pages are rendered to HTML with no client framework, then Pagefind indexes the output. Most build time went to Markdown processing and Shiki highlighting (about 40%), rendering (35%) and Pagefind indexing (12%). Warm builds benefit from the content layer cache, which skips re-parsing unchanged entries.

VitePress renders Markdown with markdown-it, compiles each page into a Vue component and server-renders with Vue. It is fast because markdown-it is fast and Vue SSR of mostly static templates is cheap. Its warm build barely differs from cold because it has little to cache — it is already mostly doing the minimum work.

Scaling From 500 to 5,000 Pages

All three scale roughly linearly with page count. Docusaurus with webpack could not complete the 5,000-page build on a standard 7 GB runner — it ran out of memory — and needed the 32 GB machine and NODE_OPTIONS=--max-old-space-size=12288. Starlight and VitePress completed on the standard runner.

Settings That Moved the Numbers

• Docusaurus: enable future.experimental_faster: true (−51%); remove unused plugins such as the blog if the site has none (−6%); set onBrokenLinks: 'warn' only in preview builds, since link checking is a noticeable share of the build on large sites; cache .docusaurus and node_modules/.cache between CI runs, as described in Caching node_modules in GitHub Actions for Faster SSG Builds.
• Starlight: persist node_modules/.astro between CI runs so the content layer store is warm (−31% on warm builds); restrict Shiki to the languages used; exclude generated API pages from Pagefind with pagefind: false in frontmatter where search results for them are unwanted.
• VitePress: already lean; the one change that helped was moving large JSON data files out of page frontmatter and into data loaders, which cut memory by 400 MB.

Beyond Build Time

Build time is one factor among several, and it should not decide on its own. Starlight ships almost no JavaScript per page and passes Core Web Vitals most easily; Docusaurus has the richest plugin ecosystem and versioning built in; VitePress is the natural choice for Vue projects and has the fastest builds. The comparison of authoring and features is in Docusaurus vs Starlight for Product Documentation and VitePress for Library Documentation. Where build time does become decisive is versioned documentation: Docusaurus versioning multiplies page count by the number of versions kept, so a 2,000-page site with four versions is an 8,000-page build.

Reproducing the Benchmark on Your Own Content

Published benchmarks, including this one, are a starting point. Content shape changes the results more than most teams expect: a corpus heavy in code blocks favours whichever framework highlights fastest, a corpus of many small pages exposes per-page overhead, and MDX with many imported components penalises frameworks that bundle every page. The benchmark here took about a day to reproduce on a second team's content, most of it spent on the conversion script.

Keep the conversion mechanical so it can be rerun: a script that copies Markdown, rewrites frontmatter keys to each framework's names (sidebar_position in Docusaurus, sidebar.order in Starlight, the VitePress sidebar config), and converts admonition syntax (:::note is shared by Docusaurus and VitePress; Starlight uses :::note via its asides as well, with slightly different title syntax). Record the exact versions, flags and machine in the results file. When the team reran the benchmark six months later after upgrading Docusaurus, the numbers were comparable because the whole setup was in a repository rather than in someone's notes.

Measured Impact

The team that commissioned the benchmark was on Docusaurus with webpack, with a 2,100-page site and three kept versions:

They stayed on Docusaurus — versioning and existing React components outweighed the remaining gap — and dropped the oldest version from the build, taking preview builds to 3.8 minutes.

Pitfalls & Rollback

• Benchmarking with different features. Search indexing and highlighting are large shares of build time; enable the same set everywhere.
• Warm caches in "cold" runs. Clear framework caches explicitly in --prepare.
• Ignoring memory. A faster build that needs a larger runner may cost more.
• Experimental flags in production without a fallback. Keep the previous configuration one commit away.
• Rollback: framework flags such as experimental_faster are single configuration lines; removing them restores the default toolchain.

Conclusion

On the same 2,000-page corpus, VitePress built in 38 seconds, Starlight in 71, and Docusaurus in 166 — or 81 with its Rspack-based faster option. All three scale linearly, and Docusaurus needs markedly more memory. Build time rarely decides the choice alone, but on large or versioned sites it should be measured early, and the framework-specific settings above recover a large share of it.

FAQ

Which docs framework builds fastest?

On the 2,000-page corpus measured here, VitePress built fastest at about 38 seconds, Starlight took about 71 seconds and Docusaurus about 166 seconds for a cold build. The ranking held at 500 and 5,000 pages, although the gaps changed with page count.

Why is Docusaurus slower?

Docusaurus compiles every page as MDX into React components, bundles them with webpack or Rspack, and server-renders each page with React. Each step is heavier than Starlight's Astro rendering or VitePress's Vue SSR. Docusaurus 3.6 and later can use Rspack through the faster option, which cut the build roughly in half here.

Does build time matter for a documentation site?

It matters for preview deploys and for how quickly fixes reach readers. A three-minute build on every pull request is tolerable; a twelve-minute build at 10,000 pages changes how teams work, because writers stop waiting for previews.

How do I benchmark fairly?

Use the same content converted to each framework's conventions, the same machine, clean caches for cold builds, several runs with hyperfine, and comparable features enabled, such as search indexing and syntax highlighting. Report memory and output size alongside time.

Related

• Parent: Docs Frameworks: Docusaurus, Starlight and VitePress — choosing a framework.
• Versioned Documentation with Docusaurus — why versions multiply build time.
• Internationalizing Starlight Docs — locales multiply it too.
• Astro vs Eleventy Build Times at 10,000 Pages — a similar benchmark for generators.
• Measuring Build Time Regressions in CI — keeping the numbers from creeping back.