Modern Documentation Frameworks

Documentation is usually described as a writing task, but the hard part is rarely the prose. The hard part is turning a hundred scattered files into a site that people can navigate, search, link to, and keep in sync with the product they describe. A documentation framework is the toolchain that makes that decision once on your behalf: you write Markdown in a repository, the framework builds it into a website, and everything else — routing, navigation, search, theming, deployment — becomes configuration instead of custom code.

This course compares the four frameworks that teams actually reach for today. They are all good, they all produce static sites, and they all look similar in a feature table. What separates them is what each one optimises for, and that is only visible once you understand how each is put together. So the course takes the frameworks one at a time, explains the model behind each, and then puts the four side by side on the axes that decide a real decision: build model and reader cost, the feature differences that show up in practice, the situations each one fits, and the work involved in moving an existing documentation set from one to another.

Where This Course Goes

The course runs in six chapters. The first establishes the vocabulary — what a documentation framework is, why teams adopt one, and how the major options differ — so that the rest of the material can be read without stopping to work out which layer a concept belongs to. The four chapters after it take the tools in turn: VitePress, Docusaurus, Astro with the Starlight theme, and MkDocs with the Material theme. The sixth chapter is the comparison, and it is the chapter most readers should care about if they are trying to make a choice.

Each tool chapter follows the same shape, so that you can move between them without relearning the structure: what the tool is and how it is built, what it feels like to work with for the first hour, and then the parts of it that are specific to that tool — the configuration model, the extension model, the content features, and how the site gets published.

What You Will Learn

  • Read a framework’s architecture on sight: place any option, file, or feature in the content, generator, or theme layer, and say which layer owns it.
  • Tell the four tools apart by what they optimise: the authoring loop, the surrounding application, the reader’s download, or the setup cost.
  • Judge output without benchmark theatre: reason about build model, runtime payload, and dev-server feedback qualitatively, and design an experiment on your own content.
  • Choose against your own constraints: map who writes the documentation, what else has to live on the site, whether versions and locales are required, and what has to stay working.
  • Plan a migration: convert frontmatter, call-outs, and navigation, preserve or redirect URLs, and verify the result by diffing two builds.
  • Configure a site end to end: write the configuration file, choose a theme, enable search, and publish the output from a CI job.

Who This Is For

  • Developers and technical writers who have to stand up a documentation site and want to understand the tool they are choosing rather than copy a configuration file.
  • Engineers maintaining an existing documentation set who need to decide whether to stay put or move, and who need a defensible answer to “why this one”.
  • Teams deciding where their documentation build should live in the stack, especially when the product, the docs, and the CI pipeline use different languages.
  • Anyone curious about how static site generators differ: the same five ideas — routing, templates, components, search, and deployment — appear in every one of them, in quite different shapes.

The only prerequisites are that you are comfortable editing Markdown and running commands in a terminal, and that you have some idea of what a web page is made of. No framework-specific knowledge is assumed, and no particular programming language is required.

Found an issue with this content?

Tell us what could be improved.