Author: Zach Corleissen (CNCF)

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 ordering, vanishing 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.