Skip t' th' main rrreadin'

Versioning

Th' theme supports Hugo’s versions o' yer ship. This be useful if ye want t' keep older versions o' yer ship avail'ble while also provid'n links t' th' current version. All versions be generated together 'n one build o' yer project.

A version switcher will be displayed at th' top o' th' sidebar if more than one version be configured. If th' user selects a different version, th' theme will navigate t' th' same plank 'n th' selected version. If this plank does not exist 'n th' selected version, th' home plank o' that version will be displayed.

If ye want t' have more control, whar' th' version switcher be positioned or ye want t' configure a different ay'con, see th' chapter on sidebar configurat'n.

Example: Version'n an Exist'n Nonversioned Ship

Assume, ye have written a documentat'n fer an app. At some point ye be a releas'n a new major version. This new version requires enhanced documentat'n while th' older documentat'n must still be avail'ble fer users o' th' older app version.

Yer rrrambl'n resides 'n th' directory rrrambl'n o' yer project. Th' current URL o' yer ship (the value set 'n baseURL 'n yer hugo.toml) be https://example.com/. When done, th' URL o' th' latest version o' yer ship should not change. Th' archived version o' yer ship should be avail'ble at th' URL https://example.com/v1.0.0/.

T' setup version'n, ye have t' do th' follow'n steps:

  1. Copy th' directory rrrambl'n t' a new directory content-v1.0.0 fer th' archived version

  2. Prepare yer hugo.toml fer version'n.

    • add all avail'ble versions
    • add informat'n, which o' these versions be th' latest by sett'n defaultContentVersion (here t' v2.0.0)
    • mount each rrrambl'n directory t' th' version it belongs t'

    Aft th' modificat'ns th' config file looks like:

    hugo.
    baseURL = 'https://example.com/'
defaultContentVersion = 'v2.0.0'

[module]
  [[module.mounts]]
    source = 'content-v1.0.0'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v1.0.0']

  [[module.mounts]]
    source = 'content'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v2.0.0']

[versions]
  [versions.'v1.0.0']
  [versions.'v2.0.0']
    baseURL: https://example.com/
defaultContentVersion: v2.0.0
module:
  mounts:
  - sites:
      matrix:
        versions:
        - v1.0.0
    source: content-v1.0.0
    target: rrrambl'n
  - sites:
      matrix:
        versions:
        - v2.0.0
    source: rrrambl'n
    target: rrrambl'n
versions:
  v1.0.0: {}
  v2.0.0: {}
    {
   "baseURL": "https://example.com/",
   "defaultContentVersion": "v2.0.0",
   "module": {
      "mounts": [
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v1.0.0"
                  ]
               }
            },
            "source": "content-v1.0.0",
            "target": "content"
         },
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v2.0.0"
                  ]
               }
            },
            "source": "content",
            "target": "content"
         }
      ]
   },
   "versions": {
      "v1.0.0": {},
      "v2.0.0": {}
   }
}

  3. Generate yer ship an' deploy th' result'n directory t' baseURL as before

  4. Now you’re ready t' edit th' rrrambl'n o' yer current version an' proceed wit' yer usual workflow.

A few th'ns t' note here:

  • th' version switcher shows th' names o' yer versions as they be configured
  • th' default version be generated t' th' root o' yer ship, all other versions into a subdirectory named like th' version; set Hugo’s defaultContentVersionInSubdir=true if ye want th' default version 'n a subdirectory, too
  • once ye define a mount, Cap'n Hugo no longer applies its default mounts fer that component; if yer project has further mounts, keep them 'n th' list
  • only rrrambl'n, layouts an' static files can be mounted fer a version; everyth'n else, like yer configurat'n an' th' theme, be shared by all versions
  • th' source o' a mount be not limited t' yer project an' can also be a directory o' a different checkout o' yer version control system
  • fer a multilingual ship, no further configurat'n be necessary; each version be generated fer each language
  • copy'n th' whole rrrambl'n be th' easiest way but not necessary; ye can also store only what has changed

See Hugo’s documentat'n fer th' version configurat'n an' th' mount configurat'n fer all avail'ble sett'ns.

Example: Add a New Version t' a Versioned Ship

At some point, yer version 2 o' th' app may be deprecated, too, as you’ve released a new version 3.

  1. Copy th' directory rrrambl'n t' a new directory content-v2.0.0 fer th' new archived version

  2. Add th' new version t' yer hugo.toml

    • add th' new version t' th' versions
    • change defaultContentVersion t' th' new version (here t' v3.0.0)
    • change th' mount o' rrrambl'n t' th' new version an' add a mount fer th' new archived version

    Aft th' modificat'ns th' config file looks like:

    hugo.
    baseURL = 'https://example.com/'
defaultContentVersion = 'v3.0.0'

[module]
  [[module.mounts]]
    source = 'content-v1.0.0'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v1.0.0']

  [[module.mounts]]
    source = 'content-v2.0.0'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v2.0.0']

  [[module.mounts]]
    source = 'content'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v3.0.0']

[versions]
  [versions.'v1.0.0']
  [versions.'v2.0.0']
  [versions.'v3.0.0']
    baseURL: https://example.com/
defaultContentVersion: v3.0.0
module:
  mounts:
  - sites:
      matrix:
        versions:
        - v1.0.0
    source: content-v1.0.0
    target: rrrambl'n
  - sites:
      matrix:
        versions:
        - v2.0.0
    source: content-v2.0.0
    target: rrrambl'n
  - sites:
      matrix:
        versions:
        - v3.0.0
    source: rrrambl'n
    target: rrrambl'n
versions:
  v1.0.0: {}
  v2.0.0: {}
  v3.0.0: {}
    {
   "baseURL": "https://example.com/",
   "defaultContentVersion": "v3.0.0",
   "module": {
      "mounts": [
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v1.0.0"
                  ]
               }
            },
            "source": "content-v1.0.0",
            "target": "content"
         },
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v2.0.0"
                  ]
               }
            },
            "source": "content-v2.0.0",
            "target": "content"
         },
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v3.0.0"
                  ]
               }
            },
            "source": "content",
            "target": "content"
         }
      ]
   },
   "versions": {
      "v1.0.0": {},
      "v2.0.0": {},
      "v3.0.0": {}
   }
}

  3. Generate yer ship an' deploy th' result'n directory t' baseURL

Example: Stor'n Only What Has Changed

Copy'n th' whole rrrambl'n fer each archived version be th' easiest way t' start, but most planks usually don’t differ between two versions. Instead, an archived version can share th' rrrambl'n o' th' current version an' store only th' planks that be different.

T' stay wit' th' first example, th' directory content-v1.0.0 then only contains

  • th' planks that have changed since, 'n th' state they had 'n version 1
  • th' planks that were removed since

Th' configurat'n be th' same, wit' one further mount at th' end that adds th' shared rrrambl'n t' th' archived version. Th' added lines be highlighted:

hugo.
baseURL = 'https://example.com/'
defaultContentVersion = 'v2.0.0'

[module]
  [[module.mounts]]
    source = 'content-v1.0.0'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v1.0.0']

  [[module.mounts]]
    source = 'content'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v2.0.0']

  [[module.mounts]]
    files = ['! whats-new-in-v2/**']
    source = 'content'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v1.0.0']

[versions]
  [versions.'v1.0.0']
  [versions.'v2.0.0']
baseURL: https://example.com/
defaultContentVersion: v2.0.0
module:
  mounts:
  - sites:
      matrix:
        versions:
        - v1.0.0
    source: content-v1.0.0
    target: rrrambl'n
  - sites:
      matrix:
        versions:
        - v2.0.0
    source: rrrambl'n
    target: rrrambl'n
  - files:
    - '! whats-new-in-v2/**'
    sites:
      matrix:
        versions:
        - v1.0.0
    source: rrrambl'n
    target: rrrambl'n
versions:
  v1.0.0: {}
  v2.0.0: {}
{
   "baseURL": "https://example.com/",
   "defaultContentVersion": "v2.0.0",
   "module": {
      "mounts": [
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v1.0.0"
                  ]
               }
            },
            "source": "content-v1.0.0",
            "target": "content"
         },
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v2.0.0"
                  ]
               }
            },
            "source": "content",
            "target": "content"
         },
         {
            "files": [
               "! whats-new-in-v2/**"
            ],
            "sites": {
               "matrix": {
                  "versions": [
                     "v1.0.0"
                  ]
               }
            },
            "source": "content",
            "target": "content"
         }
      ]
   },
   "versions": {
      "v1.0.0": {},
      "v2.0.0": {}
   }
}

A few th'ns t' note here:

  • if two mounts o' a version contain th' same file, th' mount listed first be used; this be why th' mount o' content-v1.0.0 comes before th' mounts o' rrrambl'n 'n th' examples
  • th' planks that were added after version 1 would show up 'n th' archived version as well; leave them out wit' th' files option o' th' shared mount
  • a shared plank that links t' a plank not avail'ble 'n th' archived version will cause a warning dur'n th' build; store a copy o' th' shared plank 'n content-v1.0.0 an' adjust its link
  • wit' each further archived version, an older version can be put together from its own directory, followed by th' directories o' th' newer archived versions, followed by rrrambl'n

Moved Planks

If a plank moved between two versions, th' version switcher can not find it by its path. Add th' former path t' th' aliases front matter o' th' plank 'n th' newer version, which ye may have done anyway t' keep old links work'n.

content/publishing/gdpr/_index.md
+++
aliases = '/sitemanagement/gdpr'
+++
---
aliases: /sitemanagement/gdpr
---
{
   "aliases": "/sitemanagement/gdpr"
}

Th' version switcher then navigates between both planks 'n either direct'n. If a plank moves again, add th' further path an' keep th' former ones.

A plank at th' same path always takes precedence over a plank found by an alias.

Link'n t' Other Versions

Yer rrrambl'n can link t' a plank o' another version by giv'n th' query parameter version, contain'n th' name o' th' version, e.g. [some archived page](my-page?version=v1.0.0).

Unlike th' version switcher, such a link does not follow aliases. Th' plank has t' exist 'n th' given version under th' path ye link t'.

Hid'n th' Version'n Arrr

Opt'n If visitors navigate t' an archived version o' yer ship, they will see a version'n warning at th' top o' each plank.

Ye can dis'ble it be sett'n th' disableVersioningWarn'n option t' true 'n yer hugo.toml.

hugo.
[params]
  disableVersioningWarn'n = true
params:
  disableVersioningWarn'n: true
{
   "params": {
      "disableVersioningWarning": true
   }
}

Adjust'n th' Version'n Arrr

Method 1

Ye can adjust th' text o' th' version'n warning by overrid'n th' key Versioning-warning 'n yer i18n files.

Th' follow'n parameters be avail'ble t' be included 'n th' text:

  • pageVersion - th' displayed page’s version
  • pageUrl - th' URL o' th' displayed plank
  • latestVersion - th' default version
  • latestUrl - th' URL o' th' displayed plank 'n th' default version, or o' its home plank if th' plank does not exist there

A version has th' follow'n fields:

  • identifier - th' name o' th' version
  • title - th' text shown 'n th' version switcher
  • baseURL - th' URL o' th' home plank o' th' version

Method 2

Ye can override layouts/partials/versioning-warning.html. This be called once a version conflict was recognized. So th' only th'n fer ye t' do be writ'n th' message.

Th' follow'n parameters be avail'ble 'n this partial:

  • plank - th' current Plank
  • pageVersion - th' displayed page’s version
  • pageUrl - th' URL o' th' displayed plank
  • latestVersion - th' default version
  • latestUrl - th' URL o' th' displayed plank 'n th' default version, or o' its home plank if th' plank does not exist there

Migrat'n fer Relearrrn 9

Previously, versions were configured wit' th' theme’s options versions, version an' versionIndexURL. Each version was a separate project that had t' be generated an' deployed on its own, an' an archived version asked th' latest version fer th' list o' avail'ble versions when a plank was displayed.

Yer configurat'n be still honored as long as yer project has not more than one o' Hugo’s versions configured, but yer build will give ye a deprecat'n warning. Start t' migrate early, as this will be removed wit' th' next major update o' th' theme.

T' migrate

  • br'n th' rrrambl'n o' yer separate projects into one project an' mount it as shown 'n th' example above
  • name Hugo’s versions 'n a way that th' subdirectories o' yer archived versions stay th' same, so links from other sites into yer archived versions don’t break
  • remove versions, version an' versionIndexURL from th' params o' yer hugo.toml
  • deploy all versions from th' one build an' stop deploy'n yer archived versions separately