Docs are Migrating From Jekyll to Hugo


· · · · ·

Changing the site framework

After nearly a year of investigating how to enable multilingual support for Kubernetes docs, we’ve decided to migrate the site’s static generator from Jekyll to Hugo.

What does the Hugo migration mean for users and contributors?

Things will break

Hugo’s Markdown parser is differently strict than Jekyll’s. As a consequence, some Markdown formatting that rendered fine in Jekyll now produces some unexpected results: strange left nav orderingvanishing tutorials, and broken links, among others.

If you encounter any site weirdness or broken formatting, please open an issue. You can see the list of issues that are specific to Hugo migration.

Multilingual support is coming

Our initial search focused on finding a language selector that would play well with Jekyll. The projects we found weren’t well-supported, and a prototype of one plugin made it clear that a Jekyll implementation would create technical debt that drained resources away from the quality of the docs.

We chose Hugo after months of research and conversations with other open source translation projects. (Special thanks to Andreas Jaeger and his experience at OpenStack). Hugo’s multilingual support is built in and easy.

Pain now, relief later

Another advantage of Hugo is that build performance scales well at size. At 250+ pages, the Kubernetes site’s build times suffered significantly with Jekyll. We’re excited about removing the barrier to contribution created by slow site build times.

Again, if you encounter any broken, missing, or unexpected content, please open an issue and let us know.

Zach is a Lead Technical Writer at CNCF and acts as a SIG lead for Kubernetes documentation. Prior to joining the Linux Foundation, Zach documented GitHub’s REST and GraphQL APIs and co-led the transformation of Rackspace’s developer portal. Zach holds degrees from the University of Utah (BA) and Pacific School of Religion (M.Div). He lives in Seattle and Guadalajara.


Leave a Comment

Your email address will not be published. Required fields are marked *

Skip to toolbar