Let readers choose the version they read

The version picker beside the site title decides which version of the docs readers are served: their own, one fixed version, one they choose from a list you set or from every live release line, or no picker at all.

About this task

Each reader normally gets the version their organization is entitled to, and anonymous visitors of a public site get the version of the public set. The version picker belongs to the registered repository and is kept in the database, like the access mode: staff change it, unless the docs repository declares versionPicker in the site block of its opend.config.yaml (Set the site up from opend.config.yaml), which then sets it with each build of the newest release line. New repositories have it off.

Mode	Version served	Beside the site title
`off`	The reader's own	The release label, as without a picker
`reader`	The reader's own	That version, for example Version 1.4
`fixed`	The fixed version, for everyone	That version
`list`	The one the reader chose; at first, their own	A menu of the listed versions and the reader's own, newest first
`live`	The line the reader chose; at first, their own line (at their own version), or the newest line when theirs is not live	A menu of every live release line, newest first

Open Site & access in the admin console at /admin/site.
Only staff readers can open the console. See Run your site from the admin console.
Under Version picker, choose what readers can pick: Off, Reader’s version, Fixed version, Choose from a list or Every live version.
Every live version (live) needs no list: the menu is the repository's live release lines, such as 0.23, 0.22 and 0.21 with release lines by minor version. Publishing 0.24 adds it to the menu, and retiring a line removes it, with nothing to change here. A version is matched by its line, so a cookie or request for 0.22.1 picks 0.22. A reader on a live line keeps their own version there (0.22.3 rather than 0.22), so release conditions within the line still apply to them as before; on another line they get the line's name as their version.
For Fixed version, type the version everyone gets in Fixed version, such as 2.1. For Choose from a list, type the versions to offer in Versions in the list, separated by commas, such as 2.1, 2.0, 1.4.
The hint under the field lists the release lines already published. You can list any version, such as a minor release within a line: content conditioned on release is filtered for exactly that version.
Select Save version picker.

Every replica drops its cached pages at once, so the next page shows the new picker. The change is recorded in the audit log as repo.versions.

Or set it through the admin API.

H="authorization: Bearer $OPEND_ADMIN_TOKEN"
curl -X PUT "$PUBLIC_URL/admin/api/repos/1/versions" -H "$H" -H 'content-type: application/json' \
  -d '{"mode":"list","versions":["2.1","2.0","1.4"]}'
# or {"mode":"live"}, {"mode":"fixed","version":"2.1"}, {"mode":"reader"}, {"mode":"off"}

Or set it in a seed file, next to the repository.

repos:
  - fullName: acme/docs
    sourceUrl: https://github.com/acme/docs.git
    versionPicker: { mode: list, versions: ['2.1', '2.0', '1.4'] }
    # or versionPicker: { mode: live }

A seed without versionPicker leaves the picker as it is.

Results

Only the version changes. Products and features still come from the reader's entitlements (and the public set on a public site), so a reader who switches to 2.0 sees 2.0's content for the products they hold. Release conditions and the release line follow the version served.
Listing a version opens it. Every reader may switch to any listed version, whatever their own. On a public site that includes anonymous visitors: with no public set, they then see content gated only by release, never by product or feature. A fixed version is served to everyone in the same way.
A choice is only a request. It is kept in the opend_version cookie by the picker's links (/_version?v=2.0&returnTo=/page.html) and checked on every request: a version the picker no longer offers is ignored, and the reader is back on their own. A listed version whose release line has no live release is not offered.
Release lines. A version served is mapped to its release line by the repository's setting, by major or by minor version. See Release lines by major or minor version.
Everything follows it. Pages, navigation, search, images and PDFs are served for the version chosen, and cached per version. The staff view moves to the chosen version's release line. The embedded help panel, token requests to the help JSON API and the public API are unchanged: they always use the reader's own version. Anonymous requests to the help JSON API on a public site follow the picker through their version parameter, as a visitor's choice does (see Help JSON API reference).
Defaulting to the newest version. On a public site, set the public set's version to latest (see Make a site public or private): anonymous visitors start on the newest live line, and with live the menu offers the others. Each new line becomes the default the moment it goes live.
The picker is a list of links in a <details> menu, so it works without scripts, and sits in the Menu panel on narrow screens. What readers see is described in Choose the version you read.