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 Ship

Assume, ye be writ'n 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.

This be yer intial hugo.toml file:

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 yer old ship fer version'n.
    • add an array o' all avail'ble versions t' yer hugo.toml
    • add informat'n, which o' these versions be th' latest by sett'n th' isLatest opt'n on one item 'n th' versions array
    • add informat'n, which o' these versions yer ship actually be, by sett'n th' version opt'n
    • change yer baseURL t' th' version specific URL
      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"
         }
      ]
   }
}
  2. Generate yer old ship into th' baseURL (in our case https://example.com/v1.0/)
  3. Copy ye Cap'n Hugo project into a new directory
  4. Make changes t' th' documentat'n fer th' new version
  5. Prepare yer new ship fer release.
    • leave th' previously set array o' avail'ble versions as be
    • change th' informat'n, which o' th' versions yer ship actually be, by sett'n th' version opt'n
    • change yer baseURL back t' th' original URL
      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"
         }
      ]
   }
}
  6. Generate yer new ship t' th' chosen locat'n (in our case https://example.com/)

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
  • ye can generate yer old versions into th' directory o' th' new version

Example: Add New Versions 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.

Ye only need t' create two versions o' yer ship, th' former current one an' th' new current one.

  1. Prepare yer old ship.
    • add th' new version t' th' array o' avail'ble versions 'n yer hugo.toml
    • revise informat'n, which o' these versions be th' latest by sett'n th' isLatest opt'n on one item 'n th' versions array
    • change yer baseURL t' th' version specific URL
      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/v2.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/v2.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/v2.0/",
            "identifier": "v2.0",
            "title": "v2.0"
         },
         {
            "baseURL": "https://example.com/v1.0/",
            "identifier": "v1.0",
            "title": "v1.0"
         }
      ]
   }
}
  2. Generate yer old ship into th' baseURL (in our case https://example.com/v2.0/)
  3. Copy ye Cap'n Hugo project into a new directory
  4. Make changes t' th' documentat'n fer th' new version
  5. Prepare yer new ship fer release.
    • leave th' previously set array o' avail'ble versions as be
    • change th' informat'n, which o' th' versions yer ship actually be, by sett'n th' version opt'n
    • change yer baseURL back t' th' original URL
      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/v2.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/v2.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/v2.0/",
            "identifier": "v2.0",
            "title": "v2.0"
         },
         {
            "baseURL": "https://example.com/v1.0/",
            "identifier": "v1.0",
            "title": "v1.0"
         }
      ]
   }
}
  6. Generate yer new ship t' th' chosen locat'n (in our case https://example.com/)

A few th'ns t' note here:

  • ye don’t need t' recreate version 1 o' yer ship as long as th' baseURL fer th' entry marked wit' isLatest=true hasn’t changed. Th' old versions will access th' version index o' th' latest ship t' display all avail'ble versions 'n th' version switcher

Hid'n th' Deprecat'n Arrr

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

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

hugo.
[params]
  disableVersionWarn'n = true
params:
  disableVersionWarn'n: true
{
   "params": {
      "disableVersionWarning": true
   }
}

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.