What Are Documentation Frameworks
A documentation framework is a build tool that turns a directory of text files into a browsable website. That sounds trivial, and it is — the mechanism is a template engine that reads Markdown, applies a theme, and writes HTML. What is not trivial is everything the framework quietly does on the way: it decides the URL of every page, refuses to build when a link points at nothing, generates a table of contents from your headings, gives you a search box, decides how the sidebar highlights the page you are on, and produces a directory of static files that any web server can host.
Most confusion about documentation tooling comes from mixing up three layers that these frameworks keep deliberately separate.
| Layer | Question it answers | Typical artifacts |
|---|---|---|
| Content | What does the page say? | Markdown files, front matter, images |
| Generator | How does a file become a URL? | Routing, builds, dead-link checks, search index |
| Theme | What does the page look like? | Layout, navigation, typography, colors |
Keeping the layers separate is what makes the ecosystem composable. You can move from one theme to another without rewriting a sentence of prose, and you can move from one generator to another without redesigning the site. The layer that is most often confused is the generator: teams sometimes assume that switching frameworks means migrating their content, when in most cases the Markdown files themselves survive the move untouched.
The phrase describes a workflow rather than a file format. Content lives in the same repository as the product, it goes through the same review process as code, and it is published by the same pipeline that publishes the product.
A typical page is a Markdown file with a small block of metadata at the top:
---
title: Installing the CLI
description: Install the CLI and verify that it runs on your machine.
---
# Installing the CLI
Run the installer for your platform, then check the version:
The metadata block is called front matter, and the tools use it for everything a page needs beyond its body: the browser title, the meta description that search engines and social cards read, the layout to render it in, and flags such as whether it belongs in the sidebar. Because it is data rather than prose, a generator can read the front matter of every file in the project and build a navigation tree without you maintaining a second list by hand.
The build step then turns the content tree into an output tree, following the same convention in most tools:
docs/
├── index.md -> /index.html
├── guide/
│ ├── index.md -> /guide/index.html
│ └── install.md -> /guide/install.html
└── .vitepress/
└── config.mts -> (configuration, not a page)
Note that the special directory holding the configuration is excluded from routing. That is a small detail, but it is the same in every framework worth knowing, and it explains why the configuration always lives in a dot-prefixed folder.
The output of the pipeline is normally a set of static files. This is the decision that makes documentation sites cheap, and it is worth understanding why it is not a compromise.
A static site has no server-side application to run, so there is no database to provision, no runtime to patch, and no traffic spike that can take it down. Every page can be served from a CDN, and every asset can be cached indefinitely by the host because the build writes content-hashed filenames. Search engines get complete HTML rather than an empty shell that a crawler has to execute JavaScript to fill. And because the site is just files, deployment becomes “upload a directory”, which is why a documentation site can usually be published by a single CI job with no infrastructure work at all.
The cost is that anything dynamic has to be added back deliberately. Version pickers, live API explorers, and interactive playgrounds are all possible, but they are additional work, and the framework has to be told about them rather than providing them by default.
The pattern did not appear all at once. Markdown itself was released in 2004 as a way to write readable plain text. Jekyll, released in 2008, was the tool that made the model idiomatic: it added front matter, a layout system, and a build step, and it became the default engine behind GitHub Pages, which is where most people encountered it. Hugo later brought the same model to Go with build times fast enough for very large sites. VuePress applied it to the Vue ecosystem, and VitePress replaced it with a Vite-based implementation; Docusaurus, open-sourced by Meta in 2019, carried the model into the React ecosystem with a plugin system and first-class versioning. Astro and its Starlight documentation theme brought the model into a broader “content-driven website” world where the same tool can build a marketing site and a documentation site side by side.
What has not changed across all of these is the shape of the workflow: text in a repository, a build, a directory of static files, a host that serves them. The frameworks differ in the programming language they are written in, the component model they assume, and how much they try to be opinionated about layout and navigation.
Generation is the least interesting part. The value of a framework is the set of conveniences it provides once the basic pages exist:
- Navigation derived from the content tree, with the current page highlighted automatically.
- Dead-link detection at build time, so a broken cross-reference fails the build instead of shipping.
- Search, usually a client-side index that works without a hosted service.
- Versioning and localization, so old releases and other languages are structured rather than ad hoc.
- Theming, so a brand look is a matter of variables and components rather than a stylesheet rewrite.
- Deployment defaults, including hashed asset filenames and a build output directory every static host understands.
A framework is, in other words, a large set of decisions that somebody else has already made and tested. The trade you are making is giving up some control over those decisions in exchange for not having to make them yourself.
Reading the next page, it is worth keeping this layering in mind: it explains why a “theme” can be swapped without touching content, why a “generator” owns routing, and why the configuration file tends to have two clearly separated halves — one for site-wide settings such as the base URL, and one for the theme’s own settings such as the sidebar. By the end of this chapter you will have the vocabulary to read any framework’s configuration file without guessing, and the next chapter applies it to a specific tool.
