Documentation Frameworks: An Overview
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.
The mental model is worth stating plainly, because most confusion about these tools comes from mixing up their layers. A documentation framework usually separates three concerns. The content layer is what you write: Markdown files with a small amount of metadata in the front matter. The generator layer is the build tool that turns those files into HTML, CSS, and JavaScript, and it is the part that decides how a file path becomes a URL. The theme layer is the presentation code that determines what a page looks like, how the sidebar behaves, and how search results are displayed. The separation matters because it is what makes these tools composable: you can keep the content, swap the theme, or keep the theme and change the generator, and the parts you did not touch keep working.
Because documentation is read far more often than it is rewritten, the output of this pipeline is usually a static site: plain HTML files that any web server, CDN, or object store can serve without a database or an application process behind it. That one design decision explains most of the practical benefits people notice. Static pages are cheap to host and trivially cacheable, they are readable by search crawlers without a rendering step, they do not go down when a backend does, and they can be published by a CI job that runs whenever a change is merged. It also explains the main cost, which is that anything genuinely dynamic — a live API explorer, a version picker backed by a release feed, an interactive playground — has to be added back deliberately rather than being free.
This chapter builds that model from the ground up. It defines the vocabulary that the rest of the course depends on, makes the case for adopting a framework at all rather than maintaining a folder of hand-written HTML, and then surveys the frameworks that teams actually reach for today, including the one that the following chapter takes up in detail. By the end of it you should be able to read any framework’s documentation without feeling that you have missed a layer, and — more usefully — you should be able to take a concrete set of constraints (who writes the content, whether the docs must be searchable offline, how many locales you maintain, what your hosting target is) and match them to a tool.
No framework-specific knowledge is assumed. 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. If you have used a static site generator before, you will move through this chapter quickly and can use it as a refresher; the later chapters assume the layering idea described here rather than repeating it.
