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:
baseURL = 'https://example.com/'
baseURL: https://example.com/
{
"baseURL": "https://example.com/"
}
T' setup version'n, ye have t' do th' follow'n steps:
- Prepare yer old ship fer version'n.
- add an array o' all avail'ble
versions
t' yerhugo.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 URLhugo.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" } ] } }
- add an array o' all avail'ble
- Generate yer old ship into th'
baseURL
(in our casehttps://example.com/v1.0/
) - Copy ye Cap'n Hugo project into a new directory
- Make changes t' th' documentat'n fer th' new version
- 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 URLhugo.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" } ] } }
- leave th' previously set array o' avail'ble
- 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 anidentifier
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.
- Prepare yer old ship.
- add th' new version t' th' array o' avail'ble
versions
'n yerhugo.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 URLhugo.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" } ] } }
- add th' new version t' th' array o' avail'ble
- Generate yer old ship into th'
baseURL
(in our casehttps://example.com/v2.0/
) - Copy ye Cap'n Hugo project into a new directory
- Make changes t' th' documentat'n fer th' new version
- 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 URLhugo.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" } ] } }
- leave th' previously set array o' avail'ble
- 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
.
[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
[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
.