Popular Documentation Frameworks
There is no single dominant documentation framework, and the reason is that they optimise for different things. Some assume you are writing a Vue application; some assume React; some assume you would rather not install a JavaScript toolchain at all. Picking one is therefore less about features and more about which assumptions you are willing to inherit.
| Framework | Built on | Content | Notable strengths | Main constraint |
|---|---|---|---|---|
| VitePress | Vite + Vue 3 | Markdown, Vue components | Very fast dev loop, polished default theme, optional Vue | Vue-flavoured ecosystem |
| Docusaurus | React + Node | Markdown, MDX | Plugin system, versioning, blog, i18n | React-flavoured ecosystem |
| Astro + Starlight | Astro | Markdown, MDX | Content-driven, works for site and docs together | Newer, smaller ecosystem |
| MkDocs | Python | Markdown | Minimal, Python-native, huge plugin ecosystem | Thin default theme without add-ons |
| Nextra | Next.js + React | Markdown, MDX | Deploys on Vercel/Next, built-in page search | Tied to the Next.js model |
VitePress is a static site generator built on Vite and Vue 3, and it is the tool this course covers in depth. Its defining characteristic is that Vue is optional: a site with no interactive components builds to static HTML with no client-side framework runtime at all, and Vue is only pulled in where you actually use it. The default theme is unusually complete out of the box — search, dark mode, an edit link, an outline of the current page — and the build output is small. The development server starts almost instantly and hot-updates individual pages, which is why the tool has become popular for the documentation of Vue-adjacent projects.
npm add -D vitepress
npx vitepress init
Docusaurus was open-sourced by Meta and targets React. Its distinguishing feature is the plugin system: functionality such as versioning, blog support, localization, and documentation pages are each provided by a plugin, and teams routinely write their own. It also has the most complete built-in versioning story of the tools listed here, which is why it is common in projects that ship many long-lived releases. Because it is a React application, the ecosystem around it — component libraries, testing tools, MDX support for JSX in prose — is deeper than the alternatives.
npx create-docusaurus@latest my-docs
Astro is a general-purpose content-driven site builder, and Starlight is the documentation framework built on top of it. The interesting property is that the same project can contain both a marketing site and a documentation site, sharing components, layouts, and content conventions. Starlight provides a documentation-focused default theme with search, dark mode, and a set of authoring conveniences, while Astro’s islands architecture means interactive components are hydrated individually rather than turning the whole page into a client-rendered application.
npm create astro@latest
npx astro add starlight
MkDocs takes the opposite approach: it is a small Python tool that turns a directory of Markdown into a site, with configuration in a single mkdocs.yml file and a mkdocs serve command that gives you a live-reloading preview. Out of the box its appearance is plain, which is exactly why so many Python projects use the Material for MkDocs theme, and why the plugin ecosystem matters so much: plugins are ordinary Python packages that extend the build, and they cover everything from version switchers to social cards.
pip install mkdocs
mkdocs new my-docs
mkdocs serve
Nextra is built on Next.js and targets React projects that already deploy on Vercel or another Next-compatible host. It is a natural fit when the documentation should share a deployment with a Next.js application, since it inherits the framework’s routing, image handling, and hosting model. It also provides built-in page search and a theming layer that can be customised without leaving the React component model.
npx create-next-app@latest my-docs
Start from the constraint that is hardest to change. If your team already writes Vue, VitePress is close to free and you will spend your time on content rather than on plumbing. If you write React and need multiple published versions of the same documentation, Docusaurus has the most mature support for that. If the documentation site should live in the same repository as a marketing site, Astro with Starlight keeps them in one project. If your tooling is Python and you want the smallest possible dependency, MkDocs with a good theme is hard to beat. If the whole organisation is on Next.js, Nextra avoids a second build system entirely.
If none of those apply and you are starting from scratch, the honest advice is to pick on the basis of the ecosystem you are least likely to outgrow. Every one of these tools can produce a fast, well-structured, searchable site; they differ mainly in the assumptions they bake in, and the most expensive assumption to inherit is the one you will want to undo a year from now.
Whatever you choose, the workflow described in the previous page is the same. The next chapter takes VitePress and works through that workflow end to end.
