Versioning

Opt'n Th' theme offers a way t' version 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. Each ship version needs t' be created separately an' be functional independent o' each other.

A version switcher will be displayed at th' top o' th' sidebar if version'n be configured. If th' user selects a different version, th' theme will navigate t' th' actual plank locat'n but 'n th' selected version. If this plank does not exist 'n th' selected version, th' 404 plank 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 site’s source files reside 'n th' directory /home/me/mysite on yer local disc. 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/.

This be yer intial config file before version'n:

/home/me/mysite/hugo.
baseURL = 'https://example.com/'
baseURL: https://example.com/
{
   "baseURL": "https://example.com/"
}

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

  1. Prepare /home/me/mysite/hugo.toml o' th' current version fer version'n.

    • add an array o' all avail'ble versions
    • add informat'n, which o' these versions be th' latest by sett'n th' isLatest opt'n on one item (here onto v2.0) 'n th' versions array
    • add informat'n, which o' these versions yer ship actually be, by sett'n th' version opt'n (here t' v2.0)

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

    /home/me/mysite/hugo.
    baseURL = 'https://example.com/'

[params]
  version = 'v2.0'

  [[params.versions]]
    baseURL = 'https://example.com/'
    identifier = 'v2.0'
    isLatest = true
    title = 'Latest'

  [[params.versions]]
    baseURL = 'https://example.com/v1.0/'
    identifier = 'v1.0'
    title = 'v1.0'
    baseURL: https://example.com/
params:
  version: v2.0
  versions:
  - baseURL: https://example.com/
    identifier: v2.0
    isLatest: true
    title: Latest
  - baseURL: https://example.com/v1.0/
    identifier: v1.0
    title: v1.0
    {
   "baseURL": "https://example.com/",
   "params": {
      "version": "v2.0",
      "versions": [
         {
            "baseURL": "https://example.com/",
            "identifier": "v2.0",
            "isLatest": true,
            "title": "Latest"
         },
         {
            "baseURL": "https://example.com/v1.0/",
            "identifier": "v1.0",
            "title": "v1.0"
         }
      ]
   }
}

  2. Generate th' current ship wit' th' changed configurat'n an' deploy th' result'n directory t' baseURL (here t' https://example.com/)

    • this step has not changed t' yer previous deploy, so everyth'n should be familiar until here

  3. Copy th' source files from /home/me/mysite into a new directory /home/me/mysite-1.0 fer th' archived version

  4. Prepare /home/me/mysite-1.0/hugo.toml o' th' archived version fer release.

    • change th' informat'n, which o' th' versions yer ship actually be, by sett'n th' version opt'n (here t' v1.0)
    • change th' top level baseURL t' th' URL o' version 1.0 (here t' https://example.com/v1.0/)

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

    /home/me/mysite-1.0/hugo.
    baseURL = 'https://example.com/v1.0/'

[params]
  version = 'v1.0'

  [[params.versions]]
    baseURL = 'https://example.com/'
    identifier = 'v2.0'
    isLatest = true
    title = 'Latest'

  [[params.versions]]
    baseURL = 'https://example.com/v1.0/'
    identifier = 'v1.0'
    title = 'v1.0'
    baseURL: https://example.com/v1.0/
params:
  version: v1.0
  versions:
  - baseURL: https://example.com/
    identifier: v2.0
    isLatest: true
    title: Latest
  - baseURL: https://example.com/v1.0/
    identifier: v1.0
    title: v1.0
    {
   "baseURL": "https://example.com/v1.0/",
   "params": {
      "version": "v1.0",
      "versions": [
         {
            "baseURL": "https://example.com/",
            "identifier": "v2.0",
            "isLatest": true,
            "title": "Latest"
         },
         {
            "baseURL": "https://example.com/v1.0/",
            "identifier": "v1.0",
            "title": "v1.0"
         }
      ]
   }
}

  5. Generate th' archived ship wit' th' changed configurat'n an' deploy th' result'n directory t' baseURL (here t' https://example.com/v1.0/)

  6. 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:

  • version must be an identifier o' one o' th' entries 'n th' versions array
  • ye be not limited wit' th' baseURL; these can be absolute or relative t' yer server root, can also reside 'n sub-subdirectories or be subdomains
  • ye can generate yer archived versions into a sub-directory o' th' current version (as wit' this example)
  • if ye generate yer archived versions into a sub-directory take care 'n yer workflow not t' delete older archived versions dur'n build
  • th' example does not take version control systems into account (like git or subversion) as such a workflow be highly subjective
  • both sites be completely independent autonomous Cap'n Hugo sites; if ye want t' test this setup locally, ye will need two runn'n Hugo servers
  • if ye want t' test this locally, ye will need t' adept th' top level baseURL parameter as well as th' baseURL parameter 'n th' versions array t' yer local setup; best be t' have preconfigured environment configs avail'ble

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.

Th' structure from th' previous example still applys. Yer current version o' yer site’s source files reside 'n th' directory /home/me/mysite on yer local disc, th' archived version 'n /home/me/mysite-0.1. 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/v2.0/.

Ye only need t' generate th' current an' th' new archived version o' yer ship (v3.0 an' v2.0), th' former archived version (v1.0) doesn’t need t' be generated again..

  1. Prepare /home/me/mysite/hugo.toml o' th' current version fer th' new archived version.

    • add th' new archived version t' th' array o' avail'ble versions
    • change informat'n, which o' these versions be th' latest by sett'n th' isLatest opt'n on one item (here onto v3.0) 'n th' versions array
    • add informat'n, which o' these versions yer ship actually be, by sett'n th' version opt'n (here t' v3.0)

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

    /home/me/mysite/hugo.
    baseURL = 'https://example.com/'

[params]
  version = 'v3.0'

  [[params.versions]]
    baseURL = 'https://example.com/'
    identifier = 'v3.0'
    isLatest = true
    title = 'Latest'

  [[params.versions]]
    baseURL = 'https://example.com/v.2.0/'
    identifier = 'v2.0'
    title = 'v2.0'

  [[params.versions]]
    baseURL = 'https://example.com/v1.0/'
    identifier = 'v1.0'
    title = 'v1.0'
    baseURL: https://example.com/
params:
  version: v3.0
  versions:
  - baseURL: https://example.com/
    identifier: v3.0
    isLatest: true
    title: Latest
  - baseURL: https://example.com/v.2.0/
    identifier: v2.0
    title: v2.0
  - baseURL: https://example.com/v1.0/
    identifier: v1.0
    title: v1.0
    {
   "baseURL": "https://example.com/",
   "params": {
      "version": "v3.0",
      "versions": [
         {
            "baseURL": "https://example.com/",
            "identifier": "v3.0",
            "isLatest": true,
            "title": "Latest"
         },
         {
            "baseURL": "https://example.com/v.2.0/",
            "identifier": "v2.0",
            "title": "v2.0"
         },
         {
            "baseURL": "https://example.com/v1.0/",
            "identifier": "v1.0",
            "title": "v1.0"
         }
      ]
   }
}

  2. Generate th' current ship wit' th' changed configurat'n an' deploy th' result'n directory t' baseURL (here t' https://example.com/)

  3. Copy th' source files from /home/me/mysite into a new directory /home/me/mysite-2.0 fer th' archived version

  4. Prepare /home/me/mysite-2.0/hugo.toml o' th' archived version fer release.

    • change th' informat'n, which o' th' versions yer ship actually be, by sett'n th' version opt'n (here t' v2.0)
    • change th' top levelbaseURL t' th' URL o' version 2.0 (here t' https://example.com/v2.0/)

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

    /home/me/mysite-2.0/hugo.
    baseURL = 'https://example.com/v2.0/'

[params]
  version = 'v2.0'

  [[params.versions]]
    baseURL = 'https://example.com/'
    identifier = 'v3.0'
    isLatest = true
    title = 'Latest'

  [[params.versions]]
    baseURL = 'https://example.com/v.2.0/'
    identifier = 'v2.0'
    title = 'v2.0'

  [[params.versions]]
    baseURL = 'https://example.com/v1.0/'
    identifier = 'v1.0'
    title = 'v1.0'
    baseURL: https://example.com/v2.0/
params:
  version: v2.0
  versions:
  - baseURL: https://example.com/
    identifier: v3.0
    isLatest: true
    title: Latest
  - baseURL: https://example.com/v.2.0/
    identifier: v2.0
    title: v2.0
  - baseURL: https://example.com/v1.0/
    identifier: v1.0
    title: v1.0
    {
   "baseURL": "https://example.com/v2.0/",
   "params": {
      "version": "v2.0",
      "versions": [
         {
            "baseURL": "https://example.com/",
            "identifier": "v3.0",
            "isLatest": true,
            "title": "Latest"
         },
         {
            "baseURL": "https://example.com/v.2.0/",
            "identifier": "v2.0",
            "title": "v2.0"
         },
         {
            "baseURL": "https://example.com/v1.0/",
            "identifier": "v1.0",
            "title": "v1.0"
         }
      ]
   }
}

  5. Generate th' archived ship wit' th' changed configurat'n an' deploy th' result'n directory t' baseURL (here t' https://example.com/v2.0/)

  6. 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:

  • ye don’t need t' regenerate version 1 o' yer ship as long as th' version marked wit' isLatest=true hasn’t changed its baseURL parameter. Th' old archived versions will access th' version index o' th' latest ship us'n JavaScript t' display all currently avail'ble versions 'n th' version switcher
  • wit' each new version, ye will need another Cap'n Hugo server instance t' run a complete local test

Example: Multilingual Setup

If ye have a multilingual ship an' ye have different baseURL sett'ns fer each language, ye need t' also configure version'n fer each language separately!

T' stay wit' th' above example, here’s th' configurat'n fer yer current version:

/home/me/mysite-2.0/hugo.
[languages]
  [languages.en]
    baseURL = 'https://example.com/'
    contentDir = 'content/en'
    languageCode = 'en'
    languageName = 'English'
    title = 'My Website'
    weight = 1

    [languages.en.params]
      version = 'v2.0'

      [[languages.en.params.versions]]
        baseURL = 'https://example.com/'
        identifier = 'v2.0'
        isLatest = true
        title = 'Latest'

      [[languages.en.params.versions]]
        baseURL = 'https://example.com/v1.0/'
        identifier = 'v1.0'
        title = 'v1.0'

  [languages.pir]
    baseURL = 'https://pir.example.com/'
    contentDir = 'content/pir'
    languageCode = 'art-x-pir'
    languageDirect'n = 'rtl'
    languageName = 'Pirrratish'
    title = 'Arrr, my Website'
    weight = 2

    [languages.pir.params]
      version = 'v2.0'

      [[languages.pir.params.versions]]
        baseURL = 'https://pir.example.com/'
        identifier = 'v2.0'
        isLatest = true
        title = 'Latest'

      [[languages.pir.params.versions]]
        baseURL = 'https://pir.example.com/v1.0/'
        identifier = 'v1.0'
        title = 'v1.0'
languages:
  en:
    baseURL: https://example.com/
    contentDir: content/en
    languageCode: en
    languageName: English
    params:
      version: v2.0
      versions:
      - baseURL: https://example.com/
        identifier: v2.0
        isLatest: true
        title: Latest
      - baseURL: https://example.com/v1.0/
        identifier: v1.0
        title: v1.0
    title: My Website
    weight: 1
  pir:
    baseURL: https://pir.example.com/
    contentDir: content/pir
    languageCode: art-x-pir
    languageDirect'n: rtl
    languageName: Pirrratish
    params:
      version: v2.0
      versions:
      - baseURL: https://pir.example.com/
        identifier: v2.0
        isLatest: true
        title: Latest
      - baseURL: https://pir.example.com/v1.0/
        identifier: v1.0
        title: v1.0
    title: Arrr, my Website
    weight: 2
{
   "languages": {
      "en": {
         "baseURL": "https://example.com/",
         "contentDir": "content/en",
         "languageCode": "en",
         "languageName": "English",
         "params": {
            "version": "v2.0",
            "versions": [
               {
                  "baseURL": "https://example.com/",
                  "identifier": "v2.0",
                  "isLatest": true,
                  "title": "Latest"
               },
               {
                  "baseURL": "https://example.com/v1.0/",
                  "identifier": "v1.0",
                  "title": "v1.0"
               }
            ]
         },
         "title": "My Website",
         "weight": 1
      },
      "pir": {
         "baseURL": "https://pir.example.com/",
         "contentDir": "content/pir",
         "languageCode": "art-x-pir",
         "languageDirection": "rtl",
         "languageName": "Pirrratish",
         "params": {
            "version": "v2.0",
            "versions": [
               {
                  "baseURL": "https://pir.example.com/",
                  "identifier": "v2.0",
                  "isLatest": true,
                  "title": "Latest"
               },
               {
                  "baseURL": "https://pir.example.com/v1.0/",
                  "identifier": "v1.0",
                  "title": "v1.0"
               }
            ]
         },
         "title": "Arrr, my Website",
         "weight": 2
      }
   }
}

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 opt'n 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 parameter be avail'ble t' be included 'n th' text:

  • pageVersion - th' element o' th' displayed page’s version from yer versions array
  • pageUrl - th' URL o' th' displayed plank
  • latestVersion - th' element o' th' version marked wit' isLatest from yer versions array
  • latestUrl - th' URL o' th' displayed plank mapped t' th' latest version

Method 2

Ye can override layouts/partials/versioning-war'n.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 parameter be avail'ble 'n this partial:

  • plank - th' current Plank
  • pageVersion - th' element o' th' displayed page’s version from yer versions array
  • pageUrl - th' URL o' th' displayed plank
  • latestVersion - th' element o' th' version marked wit' isLatest from yer versions array
  • latestUrl - th' URL o' th' displayed plank mapped t' th' latest version

Change URL o' th' Version Index

Opt'n Th' default URL fer th' version index can be changed wit' th' versionIndexURL parameter

hugo.
[params]
  versionIndexURL = 'myversionindex.js'
params:
  versionIndexURL: myversionindex.js
{
   "params": {
      "versionIndexURL": "myversionindex.js"
   }
}
Avast

Ye only need t' change these if ye have other own rrrambl'n created fer those URLs.

Check fer duplicate URLs by runn'n hugo --printPathWarn'ns.