Picking a docs generator is the easy part. What separates documentation that stays accurate from documentation that rots is the layer of checks around it. Here is the stack that does that.
MkDocs with the Material theme — Markdown, a single YAML config, built-in client-side search, versioning through mike, and a build that finishes in seconds. The fastest path to good-looking docs, and the one with the least JavaScript to maintain.
Docusaurus — React-based, so you can embed live components and interactive examples, with first-class versioning and internationalisation. Heavier, and you now own a Node build.
mdBook — a single Rust binary producing a fast static book. Minimal, excellent for a linear guide, limited for a large reference site.
All three take Markdown, so switching later costs less than the argument about which to pick.
Vale enforces a style guide mechanically. Point it at a ruleset — Google's and Microsoft's writing style guides both ship as Vale packages — and vale docs/ flags passive voice, first person, undefined acronyms, inconsistent product names and words your team has banned. Run it in CI at warning level first so contributors are not blocked, then raise it. The value is not grammar policing; it is that ten writers produce documentation that reads like one.
lychee './docs/**/*.md' checks internal and external links in the source, and running it against the built HTML also catches anchors broken by a renamed heading. Anchor links are the most common breakage in documentation, because renaming a heading silently invalidates every deep link to it. Run this on a schedule, not just on pull requests, since external links break without any change on your side.
Mermaid renders flowcharts, sequence diagrams and state machines from fenced code blocks, and both MkDocs Material and Docusaurus support it directly. The advantage over an image is that a diagram in text is diffable, reviewable and editable by whoever touches the code — an exported PNG from a design tool is none of those and is always the first thing to go stale. For architecture diagrams that need more structure, D2 and Structurizr take the same text-based approach.
Documentation code samples drift from the API they document. Two fixes, both cheap. Extract snippets from files that are compiled and tested — MkDocs' snippets extension and Docusaurus both support including a region of a real source file rather than a copy. Or test the docs directly: Python's doctest, Rust's doc tests and Go's example functions all run documentation examples as part of the test suite, so a signature change breaks the build rather than the reader.
mkdocs build --strict fails on a broken internal reference instead of publishing it.