Versioning

Hugo supports versioned content for docs sites that need to publish multiple releases side by side. Each version is treated as a separate site dimension, with a default version selected for visitors who have not chosen a release.

Quick setup#

1. Set the default version and define your releases in hugo.toml.
2. Keep the same relative page paths across versions.
3. Decide whether the default version should live at the root URL or in a version subdirectory.

defaultContentVersion = "v2.0.0"
defaultContentVersionInSubdir = false

[versions]
  [versions.'v1.5.0']
    weight = 10
  [versions.'v2.0.0']
    weight = 20
  [versions.'v3.0.0']
    weight = 30

Hugo sorts versions by weight, then by semantic version. If defaultContentVersionInSubdir is true, the default release is published under its own directory, for example /v2.0.0/.

Example URLs#

• /docs/getting-started/ → default version
• /v1.5.0/docs/getting-started/ → older release
• /v3.0.0/docs/getting-started/ → newer release

A simple docs layout is usually:

Then repeat the same structure for each release you want to expose. Hugo keeps the versioned URLs aligned while allowing readers to switch between versions.

Unversioned content#

Versioning is a site dimension, so not every page should be versioned. A homepage, blog, or shared landing page often needs to be mounted outside the versioned content tree if you do not want it to inherit a version prefix. In other words, Hugo treats language × version × role as separate sites, so unversioned sections need extra care.

Learn more#