Support versioning

[desimone]

It would be great to support document versioning without having to deploy separate sites per tagged release or branch.

Additional context

• https://discourse.gohugo.io/t/documentation-site-versioning/5898
• Docs versioning mechanism vuejs/vuepress#1018
• Docusaurus 2 facebook/docusaurus#789

[LisaFC]

Oh interesting. I know @RichieEscarez has been exploring stuff in this area for his site, maybe he can investigate further.

[RichieEscarez]

Right now, the easiest path is to deploy separate sites per release/branch.

That said, going solely from my experience with getting the Knative site to work (and not actually creating nor fully testing a simple site), I can provide the following details as another optional path to creating a single site with multiple versions.

What I've done for Knative in order to create multiple versions within a single site, is to put "versioned" content in multiple peer folders along side the docs folder (where 'docs' represents the latest release). But in order to get Hugo to build the other versioned docs folders, you need to address several requirements.

Example of site structure:

Given the basic directory structure:

├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

You can add additional versioned content in different folders within the content directory, for example:

content
├─ docs
├─ docs-v2
├─ docs-v3
├─ other-folder-for-other-releases....etc

Keep in mind that is is definitely not an easy route and has other downsides (search includes all versions, or all versions must be built each time, even if only one of those versioned "folders" includes a change).

Other requirements that need to be addressed:

• As it is today, Hugo uses folder names to generate content path URLs and also to determine their corresponding layout (ie. type: docs). This means that if you are to deploy only a single site, then you must define the layout type in the frontmatter of each file (since folder name of your versioned content wont match the docs layout -> type: docs).

• To complicate things more, you must also address how you use cross links in your content. For example, specifying URLs that are relative to the baseURL wont work since they would all point to the /docs/ folder. You can use the Hugo ref or relref type links since they resolve relative to the file in which its used. For example, regardless if a file that includes the link [example crosslink]({{< relref "tutorials" >}}) is in a /docs or in /docs-other-release folder, the link will resolve to the relative and correct version of the "tutorials" topic.

• Use a build script to create your directory structure from the multiple repo branches. For example, write a script that clones all your releases/branches into a single location before running the Hugo build command (ie hugo). Unfortunately this cannot be a single command unless your whole repo branch includes only the other-docs-release content. For example, if you completely branch your whole site for each release, you will need to clone and then copy only that version's docs folder into the site that you want to build (and give that folder a different name...docs-v2).

• Main menu configuration must be set in your config.toml (and not defined within your file's frontmatter) so that the build does not find multiple entries for the same menu elements.

Im going from memory here so I'm certain that I've likely missed something but I think ive highlighted the main points.

Note: I've intentionally not linked to any of specific Knative file since that site includes several other modifications and uses multiple repos. Therefore its more complicated and does not clearly reflect the model described above.

[xiaods]

need this feature

[bbros-dev]

In case it helps the mike utility adds this functionality to MkDocs:

https://github.com/jimporter/mike

We are one day into Hugo so we can't offer any insight into how applicable this approach is to hugo.

[emckean]

Does this solve your use case? https://www.docsy.dev/docs/adding-content/versioning/

[simonspa]

Does this solve your use case? https://www.docsy.dev/docs/adding-content/versioning/

No it does not because it requires multiple full versions of the website to be deployed. What the OP would like to achieve is to have versioning without the need to replicate everything, including parts of the website not even belonging to the versioned docs.

[fekete-robert]

As others have said, versioning doesn't work out of the box as it does with some other documentation systems, but with some effort you can make it work. Admittedly, depending on your requirements, needs, and environments, it might be difficult to do so.

For the https://kube-logging.dev/ site we have implemented a method that doesn't need to rebuild everything, but it has some tricks and builds on GitHub Actions and the site being hosted on GitHub Pages. The main points I remember are:

• The different versions are on separate github branches called release-, the master branch is the latest version.
• The latest version is the main part of the site.
• Older versions are built separately, using dedicated github actions, with a baseurl /
• The site is put together on a separate branch, with the build from the master branch being the main part, while the builds from the versioned branches are copied to /
• Since the github actions only run their respective builds when there is a new commit on their respective branches, so only the part of the site is rebuilt that has changed.

IIRC, these are the basics of the setup, you can check the details in the github repo (I think there is still a github workflow called publish.yaml that we don't actually use anymore, publish-main and the publish-.yamls are the real ones).

There are some problems that the stuff I've written so far doesn't address, like:

• adding canonical urls to the older versions so they don't show up in google searches and don't count as duplicate pages
• when you have a new version, the releases menu is not automatically updated for the older versions
• depending on which search engine you use on the site, hits to pages in the old versions might or might not show up in the search results
  We have added customizations to solve these problems (some trivial, some maybe overengineered), but I have to look up exactly how - let me know if you are interested.

[timestee]

need this feature