Do you actually need a static site generator?

A generator turns a folder of Markdown into HTML. Everything good about that follows from the output being plain files with no application behind them.

• Speed. There is no server rendering anything per request, so a page is as fast as the network.
• Cheap, sturdy hosting. Files on a CDN. Nothing to patch, and a traffic spike is a bandwidth bill rather than an outage.
• Diffable content. Markdown in a repository reviews like code, which is the single best thing that ever happened to technical writing.
• No lock-in at the format layer. Your content is text files that will open in anything, forever.
• Extensibility. Plugins that generate API reference from source, pull in a changelog, or check every link at build time.

That list is genuinely strong, and it explains why generators won. But read it again and notice how much of it is about the *output* rather than about you running the generator. Speed, cheap hosting and plain-text content are properties of any static docs site, whoever builds it.

Getting a generator running is an afternoon and it is genuinely satisfying. The cost is not the afternoon. It is the standing obligation you signed up for without noticing.

• A build environment — a Python or Node version, a lockfile, and the day the runner image changes underneath it.
• A CI workflow that someone owns, and that will eventually fail for a reason unrelated to your writing.
• A theme that gets updates, and occasionally a major version with breaking changes.
• Plugins, each of which is a small dependency with its own opinions about compatibility.
• Hosting, DNS and a certificate, which are easy until the person who set them up has left.
• A publishing path a non-engineer cannot use, which quietly decides who is allowed to write.

The last one is the expensive one and it never appears on a comparison table. If publishing requires a pull request, then support, sales and the founder do not update the docs. The docs become an engineering artefact, and everything those people know stays in Slack.

A worked example of the drift

The most common failure is not dramatic. The site builds fine for eight months, then a dependency in the theme needs a newer runtime, the pinned version in CI is now unsupported, and updating it turns out to require touching three other things. Meanwhile the docs are a week out of date and the person who could fix the pipeline is mid-sprint. Nothing is broken enough to prioritise, which is exactly why it stays broken.

These are good reasons and no hosted service should talk you out of them.

• Docs version with the code. They live in the same repository, review in the same pull requests, and a release tag has to produce matching documentation.
• Reference is generated from source. Docstrings, an OpenAPI file, a schema. A plugin does this and nothing hosted will.
• The build must run offline — an air-gapped network, or a compliance rule that forbids sending content to a third party.
• You need a theme you control, because your docs are part of a product surface with design requirements a settings page cannot express.
• You already have the pipeline and someone who likes it. This is a completely valid reason. Do not fix it.

If two or more of these are true, self-host. It is free, the tools are good, and the constraints are ones a hosted platform cannot design around.

The three cases below are extremely common, and in all three a generator is a route rather than a requirement.

The docs are prose, and the writers are not engineers

A handbook, an onboarding guide, a support knowledge base, a set of runbooks. Nothing is generated from source, and the people with the knowledge do not work in a repository. Every layer of pipeline between them and the page is a reason a page does not get updated.

You are one person, and the pipeline is the project

A solo maintainer or a small team where the docs infrastructure is competing for time with the actual product. The generator is not the constraint; attention is.

You wanted a fast searchable site and were handed a build system

This is the biggest group. Nothing in the requirements said "static site generator" — they said search, navigation, a domain, something that loads quickly. A generator provides those, and so does anything else that produces a static site.

Answer these five honestly and the answer usually falls out.

If the top three are all no and either of the bottom two is yes, you are maintaining a build system to get a website, and the build system is not the part you wanted.

Worth knowing: choosing hosted does not have to mean leaving the format. Docszero builds with Zensical, written by the Material for MkDocs team as their successor, and Export source hands back your Markdown with a config that builds with plain Zensical — so the generator route stays open the whole time.