Versions
If a product supports several versions, its documentation usually needs versions too. The theme provides a navbar version switcher and an archive banner on older sites. The site selects the deployment layout. The theme does not build across versions. Each version requires a separate Hugo build.
The version switcher
List the menu versions under params.versions. If the list is nonempty, a
branch-icon menu appears in the navbar’s utility area. An icon-only upward
menu in the footer’s bottom bar shows the same content.
A menu entry shows its version value by default. If name is given, it
shows that name. An entry is selected if its version equals
params.version or its url equals the site’s baseURL.
An entry without a url is a gray item that cannot be clicked. You can use
it as a group heading. name: '---' creates a divider. A url on a divider
causes a warning. name accepts inline Markdown:
The same list supplies “switch version” in the command palette. The menu and palette therefore agree.
The trade-off in page-for-page links
version_menu_pagelinks: true appends the current page’s path to the target
version’s URL. Version switching thus keeps the reader on the same document.
The target version may not have that page. Documentation structure can change between versions. If an older version lacks a new page, switching to it produces a 404. This site leaves the option off.
A single entry can override the global setting:
Enable it where the structure is stable. Disable it where the structure changed. An extra step to a version’s home page is preferable to a 404.
The archive banner
If a version is no longer maintained, identify its site as a snapshot:
With archived_version: true, a banner appears at the top of every
documentation and book page body. It states that the current version is no
longer actively maintained and links to url_latest_version. The text uses
the site’s language. You do not need to write it. The banner shows the
version value as its version number.
The banner appears on documentation and book pages only, not on blog or landing pages.
params.version versus params.versions
These two parameters have different purposes:
params.versionsis a cross-site list. It identifies the versions available in the menu and their locations. It describes other sites.params.versionidentifies this build’s version. It selects the menu entry and supplies the archive banner’s version number. It is also the fallback whendata/download/*.yamlomitsversion. See Releases and downloads.
It does not have to be a Git ref. If you need a resolvable release tag, declare
a separate parameter. For example, an install command can use that parameter.
Do not reuse params.version for this purpose. The full definitions of both keys are in
Configuration.
Deployment layouts for multiple versions
| Layout | baseURL |
Characteristics |
|---|---|---|
| Subdomain | https://v1-9.docs.example.com/ |
Versions are fully independent. Each needs its own DNS and certificate |
| Subpath | https://docs.example.com/v1.9/ |
One domain concentrates SEO weight. The host must route paths to different artifacts |
Each version is an independent build. Check out its content from the branch or
tag. Build with that version’s hugo.yml. Publish to the matching address.
The current version’s site lists every version. Older sites list them and add
the archive banner.
baseURL must include the path segmentOtherwise the search index, page actions and asset links all point at the domain root. The page looks correct, but search returns nothing. This is the most common subpath failure. For deployment details, see Deploy.
Verify
Run from your site’s root after a production build. In the commands below, replace
public/docs/getting-started/index.html with an actual generated documentation
page in your site (including a language prefix if needed).
-
After a build, confirm the version menu reached the page:
With
params.versionsempty or unset, the menu is not generated at all. -
Check whether the current version is marked selected:
If there is no result,
params.versiondoes not match an entry’sversionfield, orbaseURLdoes not match that entry’surl. Check the trailing slash. -
Visit each menu link. With
version_menu_pagelinksenabled, switch from a document that an older version lacks. Confirm that the destination is acceptable. -
On an archived site, open a documentation page. Confirm that the banner appears at the top of the body. It should use the site’s language and link to the current version.
-
Press ⌘/Ctrl + K to open the command palette. Confirm that “switch version” lists the same versions.
Related
- Navigation and menus — where the version menu sits in the navbar and sidebar
- Command palette — “switch version” in the palette
- Deploy —
baseURL, subpaths and multi-target publishing - Releases and downloads — download data falling back to
params.version - Configuration — full definitions of
version/versions/archived_version