By Patrice Chalin

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 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:

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 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 — 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:

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