Choosing a Framework

A framework recommendation is only useful if it comes with the situation attached, because the four tools covered in this course are close enough in capability that any of them will produce a working documentation site. The interesting question is not “which one is best” but “which one is best for a project with these constraints”, and the constraints are usually about people and about what else has to live on the site.

This page works through the situations that come up repeatedly and gives a default answer for each, naming the condition under which the answer flips.

A small internal reference, maintained by a Python team

This is the situation where MkDocs is the default answer, and the reason is not the output but the setup. A team that maintains an internal reference for a Python service does not want a JavaScript toolchain in the build. Adding one means a lockfile to keep current, a second ecosystem for contributors to install, and a set of failure modes that have nothing to do with the documentation. MkDocs installs and builds with one command each, and produces output that any static host serves. Material for MkDocs gives it a search box, a proper navigation, and a dark mode, so the smallness of the core does not mean a small result.

The condition that changes the answer is who writes the pages. If the documentation is written by the same people who write the product code, and the product is in TypeScript, a Vite-based tool gives a better authoring loop and a shared toolchain. MkDocs remains the right answer whenever adding a Node toolchain is the largest single change in the plan.

A public product reference that needs versioned archives

This is Docusaurus’s home ground, and the reason is the word “versioned”. A public reference for a product with a long release history needs to serve readers who are still on an old release: the current manual, the previous manual, and sometimes several older ones, each complete, each searchable, each with URLs that must keep working after the next release. Docusaurus implements this as a first-class feature: you snapshot the documentation at a release, the snapshot becomes a version, the version selector appears in the header, and old URLs keep resolving.

The other three tools can do the same thing with directories and a little custom work, and for a project with two or three versions that work is small. But it is work you own forever, and it is the kind that gets skipped and then regretted. If versioned documentation is a stated requirement rather than a hope, start with the tool that has it.

Documentation that lives beside a marketing site and a blog

The second time Docusaurus earns its complexity is when the documentation is only one of several things the site must do. Docusaurus treats a documentation set, a blog with tags and archives, and a product landing page as three kinds of content in one project, sharing one navigation model, one theme, one build, and one deployment. For a company whose public presence includes a changelog, a blog, and a manual, that consolidation removes a category of duplicated work — one design system, one analytics configuration, one place where a broken link is caught.

Starlight can do this too, because it is an Astro site and Astro sites can have pages, but the blog, the landing page, and the documentation would be assembled from Astro’s own primitives rather than from a documentation-aware application. That is a reasonable choice when you want full control of the marketing side and a documentation site that shares nothing with it, and a heavier one when the point was to share everything.

A documentation site that must reuse the company’s React components

If the product is a React application and the documentation needs to embed its actual components — a live pricing table, an interactive form, a chart that uses the same component the product uses — then the component model has to match. Docusaurus makes this the easiest because its content is MDX and its components are React, so an existing component is imported and rendered like any other. VitePress does the same for a Vue codebase. Starlight is the most flexible, because it can host components from several frameworks in the same site and hydrate each one as an island, so the React component does not force the site to become a React application.

MkDocs is the hardest fit here, because there is no component layer in the output at all. Embedding a live component means writing a plugin and a build step, which is a much larger job than importing a component.

A site on a private network, with no third-party services

A documentation site that is only reachable inside a company network raises the question of what may be called from the reader’s browser. Any hosted search, any analytics script, and any font loaded from a third-party CDN either fails behind a restrictive firewall or leaks usage to a party the organisation has not assessed. All four tools can ship a self-contained site, but the effort differs.

MkDocs Material with its built-in local search and a self-hosted font directory is the least work. VitePress and Starlight also build a local search index at build time and ship everything they need. Docusaurus can be configured to avoid third-party requests, but its first-party search story is a hosted service, so a local search plugin becomes an extra dependency to evaluate and keep current.

A documentation set with heavy interactive content

If the pages are not really documents but applications — a live API explorer, a component playground, an interactive tutorial with state — then the question is no longer which generator renders fastest but which one lets you build those things without fighting the tool. Here the component frameworks win, because the interactive parts are ordinary components in an ordinary framework, and the generator is happy to host them. VitePress and Starlight are the most natural fits, because the interactive part is a first-class citizen of the model rather than something inserted into a text pipeline.

How to decide when the situations do not fit

The situations above cover most decisions. When they do not, three questions settle it quickly. Who will maintain the build, and what do they already know? What else has to be published on the same site? And what does the content need to do in two years that it does not do now? The answers map onto the tools directly: a Python-only team points at MkDocs, a React product with versioned public manuals points at Docusaurus, a Vue product or a repository that already runs Vite points at VitePress, and a content-first project that wants minimal output and no framework lock-in points at Starlight.

The remaining advice is procedural and matters more than any of the answers. Try the leading candidate on a real page from your own documentation — a page with code blocks, a call-out, and a table — before committing. That hour of setup will tell you more than any comparison table.

Found an issue with this content?

Tell us what could be improved.