Hugo
Comparing Documentation Site Generators — Hugo, MkDocs, Docusaurus, Starlight: Which One to Pick
Once you've decided to build your team docs as a static site, the next question is which tool to build it with. We compare Hugo, MkDocs, Docusaurus, and Starlight across runtime, search, versioning, and ceiling, and lay out which to choose for which situation.
Build a Manual with Hugo #6: Maintenance — Search Index, Accessibility, Documentation Culture
The final post in the series. We close it out with the operations perspective: a Pagefind search index for docs that have grown large, accessibility so everyone can read, and a Docs as Code culture that keeps docs alive for the long run.
Build a Manual with Hugo #5: Multilingual Content and Versioning
We cover serving one set of docs in several languages and keeping old docs around as the product version goes up. We walk through Hugo's multilingual configuration and translation linking, plus a practical, folder-based way to handle versioning, which Hugo has no built-in feature for.
Build a Manual with Hugo #4: Deploying to Cloudflare Pages and Connecting a Domain
We send the docs we built locally out into the world. We cover pushing to GitHub, connecting to Cloudflare Pages and setting up the build, and attaching a custom domain. We also point out Hextra's Go module and the publish-date trap along the way.
Build a Manual with Hugo #3: Writing Content — Code Blocks, Mermaid, Callouts
We cover three elements that make docs pleasant to read. From code blocks that carry filename and line highlighting, to Mermaid diagrams drawn as code, to callouts that make cautions and warnings stand out — we cover how to use each in Hextra.
Build a Manual with Hugo #2: Sidebar and Search — Shaping the Information Architecture
Even as your docs grow to dozens of pages, the sidebar and search are what keep readers from getting lost. We cover shaping the sidebar hierarchy from the folder structure in Hextra, ordering it with weight, and attaching the top menu and the built-in search.
Build a Manual with Hugo #1: From Install to Your First Doc
We build the skeleton of a team documentation and product manual site with Hugo and the Hextra theme. From installing Hugo Extended and Go to creating a new site, wiring up the theme, and serving your first doc with the local server, we do it all in one pass.