Technical Documentation Versioning
with Hugo & Netlify



Nate Waddington
nwaddington@cncf.io


width:300

Introduction

Technical Documents Versioning is an intersection of:

Changes + Language + Navigation + Search


For small to medium sized sites using one language/location, a folder based method is likely the best method to balance these considerations.

Versioning Considerations

What are the main concerns when versioning technical documentation in a website?

  • Readers
  • Maintainers / Writers
  • Necessity (Does the documentation need versioning yet?)
  • Navigation
  • Searchability
  • Localization / Internationalization
  • Compartmentalization
  • Switchability

Versioning Schemes

For a Hugo / Netlify setup:

friendly schemes unfriendly schemes
None (don't version)
Folder based Query Strings
Subdomain based Cookies

Folder based

Folder based

Each version of the documentation is placed in its own folder

content
└── docs
    ├── _index.md
    ├── v1
    ├── v2.2
    │   ⋮
    └── v3.4.0

Folder based navigation code example

velero.io /site/layouts/docs/versions.html

<div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    {{ $original_version := printf "/%s/" .CurrentSection.Params.version }}
    {{ $latest_url := replace .Params.url .CurrentSection.Params.version .Site.Params.latest | relURL }}
    {{ $currentUrl := .Permalink }}

    {{ range .Site.Params.versions }}
        {{ $new_version := printf "/%s/" . }}
        <a class="dropdown-item"
           href="{{ replace $currentUrl $original_version $new_version | relURL }}">{{ . }}</a>
    {{ end }}
</div>

Batard (2020, L8-L18)

velero.io velero/site/config.yaml

  versioning: true
  latest: v1.5
  versions:
    - main
    - v1.5
    - v1.4
    - v1.3.2
    ⋮

Brubaker et al. (2020, L14-L20)

Subdomain based

Subdomain based

Each version of the documentation is its own site

  • Uses git feature branches rather than folders to organize versions
  • Separate site in Netlify for each version supported
  • Simpler template code, more complex config

Subdomain based navigation code example

https://kubernetes.io website/layouts/partials/navbar-version-selector.html

<div class="dropdown-menu dropdown-menu-right" aria-labelledby="navbarDropdownMenuLink">
	{{ $p := . }}
	{{ range .Site.Params.versions }}
	<a class="dropdown-item" href="{{ .url }}{{ $p.RelPermalink }}">{{ .version }}</a>
	{{ end }}
</div>

Pursley et al. (2020, L4-L9)

https://kubernetes.io website/config.toml

[[params.versions]]
fullversion = "v1.20.0"
version = "v1.20"
githubbranch = "v1.20.0"
docsbranch = "master"
url = "https://kubernetes.io"

[[params.versions]]
fullversion = "v1.19.4"
version = "v1.19"
githubbranch = "v1.19.4"
docsbranch = "release-1.19"
url = "https://v1-19.docs.kubernetes.io"
⋮

Bannister et al. (2020, L180-L192)

Summary

Version using folders if:

  • maintainer ease of updates is a priority
  • localization / internationalization not a priority
  • it is important that only the documentation is versioned

Version using subdomains if:

  • localization / internationality is planned
  • compartmentalization not a priority

For small to medium sized sites using one language/location, a folder based method is likely the best method to balance versioning considerations.

Questions?

References / Credits

Bannister, T. et al. (2020, December 23). kubernetes/website. GitHub. Retrieved
    February 2, 2021 from https://github.com/kubernetes/website/blob/
    7462297ee388332a7b0d27625929fbf44d0c1ea9/config.toml
Batard, T. (2020, August 13). vmware-tanzu/velero. GitHub. Retrieved January 19,
    2021 from https://github.com/vmware-tanzu/velero/blob/
    db403c6c54b0048fada2b5db628c44be4ac0fd79/site/layouts/docs/versions.html
Brubaker, N., Rosland, J., Thompson, C., Batard, T. (2020, September 16). vmware-
    tanzu/velero. GitHub. Retrieved February 2, 2021 from https://github.com/vmware-
    tanzu/velero/blob/1fd49f4fd66ecf6cd959ce258efbd9a549d8902b/site/config.yaml

Pursley, B., Horgan, C., Takahashi, S. (2020, July 21). kubernetes/website. GitHub.
    Retrieved February 2, 2021 from https://github.com/kubernetes/website/blob/
    072d4b41b45f5311538c24d375432a755f9e3f4c/layouts/partials/
    navbar-version-selector.html






Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License.

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