Versions

Let readers move between documentation versions, and mark archived ones.

Categories:

Configuration

When a product has several supported releases, the documentation usually follows. OINK provides two things: a version switcher and an archived version banner.

How each version is deployed is up to you — commonly one subdomain or subpath per version, each built separately.

List the versions that should appear in the menu under params.versions:

params:
  version_menu: v2.1
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v2.0
      url: https://v2-0.docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com

version_menu , string: The label on the menu button, usually the current version.
versions[].version , string , required: The version identifier shown on the menu entry.
versions[].url , string , required: That version’s documentation address. An entry with no URL renders as unavailable.
version_menu_pagelinks , boolean , default: false: Whether to append the current page path to the target version’s URL.

Insert a separator with - name: '---' to divide supported from historical releases:

params:
  versions:
    - name: '**Current**'
    - version: v2.1
      url: https://docs.example.com
    - name: '---'
    - name: '**Historical**'
    - version: v1.9
      url: https://v1-9.docs.example.com

The page-level switching trade-off

version_menu_pagelinks: true appends the current page path to the target version’s URL, so a reader switching versions stays on the same document.

The cost is that the target version may not have that page. Documentation structure evolves between releases, an older version may not contain a newly written page, and the reader lands on a 404.

params:
  version_menu_pagelinks: true
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com
      pagelinks: false # structure differs too much; go to the home page

pagelinks: false on an individual entry overrides the global setting so that version only ever receives its home page.

Enable pagelinks when structure is broadly stable across versions.

When it is not, leaving it off is better: an extra click beats a 404.

On a site for a release you no longer maintain, say so explicitly:

params:
  archived_version: true
  version: v1.9
  url_latest_version: https://docs.example.com

archived_version , boolean , default: false: When true, shows an archive notice at the top of every page.
version , string: The version shown in the banner.
url_latest_version , string: The current version’s address; the banner links to it.

The banner text is localized with the site language; you do not write it.

Deployment layout

Two common arrangements:

Layout	`baseURL`	Character
Subdomain	`https://v1-9.docs.example.com/`	Fully independent versions
Subpath	`https://docs.example.com/v1.9/`	One domain; needs path routing

Under a subpath deployment, baseURL must include that path, or

the search index, page actions, and asset links all point to the wrong place. This is the most common subpath failure.

Each version is built independently: check out the content from its branch or tag, build with that version’s own hugo.yaml, and publish the output to the matching address. OINK does not build several versions in one pass.

Next steps

Languages: combining languages with versions
Deployment: publishing each version

JavaScript is required to load comments. View discussions on GitHub.

Versions

Version menu

The page-level switching trade-off

Archived version banner

Deployment layout

Next steps