Why some top-velocity projects use Hugo and Docsy to publish technical documentation
Some of CNCF’s top-velocity projects — such as Kubernetes, OpenTelemetry and gRPC — use Hugo as their static website generator. Why? Because Hugo is feature-rich, flexible, and fast — even for large sites.
How fast? It takes Hugo less than 30 seconds* to generate the 5600+ pages of technical documentation (written in 15 natural languages) of the kubernetes.io website, providing a delightful experience for all contributors.
Docsy: a theme for technical documentation
Most Hugo-enabled CNCF projects use the Docsy Hugo theme because it provides key features in support of publishing technical documentation that is easy to navigate, search, and contribute to. Out-of-the-box, Docsy provides support for these key features, and more:
- Multilingual and multi-versioned documentation
- Breadcrumbs, auto-generated doc-navigation and in-page table of contents
- Site search
- In-page view-page-source and page-edit links — making it easy for one-time contributors to submit minor changes like typo fixes.
By using a theme like Docsy, CNCF projects (1) can get their technical documentation online more quickly with the core features listed above (fast initial setup), and (2) let their technical writers and community members focus on creating and maintaining content, rather than creating/fixing site layouts, style files, and Hugo template code.
Docsy was open sourced by Google in 2019. Its creation, from a year or so earlier, was motivated by a pressing demand — from the over 2000 open source projects at Google — to make it easier for projects to publish their documentation. Use of Docsy continues to grow at Google (with protobuf.dev most recently being converted to use Docsy), the CNCF, and elsewhere.
Contributing to Docsy
As a member of the CNCF techdocs team, I have been contributing to Docsy for the past two years. Initially, I upstreamed fixes made to Docsy while working on gRPC.io — such as this homepage/top-nav style improvement. Since then, I’ve filed over 100 issues (60% of which have been resolved), and committed over 140 changes, most of which seek to improve usability in the following ways, for example:
- Packaging: making Docsy available as an NPM package, and eliminating the need for recursive git submodules. (Similar in spirit, another community member implemented Docsy support for Hugo modules.)
- Customizability (styling), by removing hard-coded styles in Docsy layout files.
- Google Analytics 4 (GA4) support
Most CNCF projects have similar needs for their websites, so upstreaming Docsy improvements benefits all Docsy-enabled CNCF projects, as well as the Docsy users at large. That’s the spirit of open source!
Steering Docsy’s evolution
In early 2022, I joined the Docsy Project Steering Committee (PSC). I welcomed the privilege to influence Docsy’s evolution: my primary goal has been on enhancing Docsy’s ease-of-use and customizability — examples of which were given above.
With this privilege also comes responsibilities, like reviewing community contributions, and rolling up our sleeves to coordinate and contribute to multi-person efforts for broadly-scoped changes such as upgrading Docsy to Bootstrap 5.
Contributors welcome!
The steering committee’s first order of business in 2023 will be upgrading Docsy to Bootstrap 5. Docsy is in feature freeze until this Bootstrap major-version upgrade is completed, because the currently used version of Bootstrap reached its end of life last fall. This upgrade will have an effect on almost every Docsy layout file, so contributors are most welcome for this multi-person effort, or any other Docsy issue!
*4 GHz Intel i7 quad-core, 32 GB RAM
