Technical Documentation Versioning
with Hugo & Netlify



Nate Waddington
nwaddington@cncf.io


width:300

Things to consider when thinking about versioning documentation

2 viable schemes available (for Hugo/Netlify)

Dropdown menu navigation code examples

trade offs

Readers: ease of navigation/understanding

Maintainer: how hard is it to update when it's time to cut a new version?

Necessity: YAGNI - you ain't gonna need it

Navigation: Differences between versions (how do you deal with pages that have been added, removed, or moved between releases?)

Searchability: Does the duplication of pages affect search results? How do you manage result priority between versions

Localization/internationalization: how does the added complexity of language/locale versions affect the version system

Compartmentalization: Does all of the site need to be versioned?

How do we avoid versioning the entire site if only Documentation versions are the goal?

Switchability: How easy is it to change versioning schemes

Because Hugo is a static site generator, and

Netlify abstracts a lot of the server away

Query Strings and Cookies don't really work for a Hugo / Netlify site

Scores high on: - Maintainer ease of updates - Compartmentalization

This is probably the easiest way to start versioning.

Scores low on: - Localization / Internationalization

Can make code more complex

One of the things that make this a good example is how Batard (2020, L8-L18) manages the navigation in the `/site/layouts/docs/versions.html` file, particularly the use of the `replace` function to ensure that when the links in the dropdown menu are built, the versioned links reflect the currently loaded page:

Can make configuration less complex

Scores high on: - Localization / Internationalization

Scores low on: - Compartmentalization

Scores low on: - Maintenance, each version is its own site

The subdomain scheme uses some simpler template code to generate links, only having to update the `.url`, but the Hugo config file is made more complex.

same style of dropdown function as before, made simpler

dropdown example is made simpler because the config is more complex

and because the server setup is more complex

and not, for instance, the blog

some work is being done on k8s to address compartmentalazion, but it is ongoing