Comparing Frameworks and Choosing One

Choosing a documentation framework is easy to get wrong, because the four tools covered in this course are all good and the reasons to prefer one over another are rarely technical at the moment of comparison. The published feature lists overlap heavily: all four render Markdown to static HTML, all four can search, all four have a dark mode, and all four are free. If you compare them on those features you will finish with an arbitrary answer.

The comparison that actually discriminates runs along a smaller number of axes, and they are axes about your project rather than about the tools. The first is the authoring model: whether the people who write the documentation are comfortable in the toolchain the tool implies. A Python team that will never install Node is not choosing between two JavaScript frameworks; they are choosing between a Python tool and a JavaScript one, and the second is already more expensive than it looks. The second is the extension model, because it determines what happens the first time a page needs something the theme does not provide: in one tool that is a Python plugin, in another it is a React component, in a third it is an Astro island, and the cost of each is different by an order of magnitude. The third is the output model, which determines what a reader downloads and what a hosting platform has to support. The fourth is the growth model: how the documentation set is expected to change, whether it needs versioned archives for readers on old releases, whether it must be published in several languages, and whether the same repository will eventually host a blog and a product page alongside the reference.

Those axes matter because each framework is a different answer to them. VitePress spends its complexity on the authoring loop, leaning on Vite to make the edit-and-preview cycle fast and on Vue only where a page genuinely needs interactivity. Docusaurus spends its complexity on the surrounding application, treating the documentation site as one part of a larger React project with a blog, a landing page, and versioned archives. Astro with the Starlight theme spends its complexity on the output, sending no framework code to a reader unless a component asks for it. MkDocs spends almost none at all, which is why it is quick to adopt and why its extension path runs through Python plugins and themes rather than through components.

This chapter makes those axes explicit and works through them one at a time. It compares the four tools on build model and runtime cost, on the features that differ in practice rather than in name, on the situations each one fits, and on what it costs to move a documentation set from one to another. The aim is not to name a winner. Each of the four is the right answer for a different set of constraints, and the useful skill is the one that maps a constraint onto a tool. What that mapping looks like is deliberately not a table of winners; it is a sequence of questions whose answers point at a default, and the questions are stated so that you can answer them about your own project rather than about a hypothetical one.

Chapters

Found an issue with this content?

Tell us what could be improved.