🏷️ Version switcher#

Enable users to switch between different versions of your documentation.

Configuration#

Configure the version switcher via html_context in conf.py:

html_context = {
    "version_id": "v2.0",
    "version_switcher_url": "https://example.com/docs/_static/switcher.json",
}

Key	Description
`version_id`	The currently displayed version
`version_switcher_url`	URL to the JSON file containing version data

Version JSON format#

Create a switcher.json file with your available versions:

[
  {
    "name": "v2.0 (stable)",
    "version": "stable",
    "url": "/en/stable/",
    "preferred": true
  },
  {
    "name": "v2.1 (latest)",
    "version": "latest",
    "url": "/en/latest/"
  },
  {
    "name": "v1.0",
    "version": "v1.0",
    "url": "/en/v1.0/"
  }
]

Each version object accepts:

Key	Description
`name`	Display name in dropdown
`version`	Version identifier (matches `version_id`)
`url`	Base URL for this version
`preferred`	Optional. Mark as the recommended version

Read the Docs integration#

For Read the Docs, use environment variables:

import os

version_id = os.environ.get("READTHEDOCS_VERSION", "latest")

html_context = {
    "version_id": version_id,
    "version_switcher_url": "https://raw.githubusercontent.com/org/repo/main/docs/_static/switcher.json",
}

Hosting the JSON file#

The switcher.json can be:

In your repository - Served via GitHub raw URLs or your documentation static files
External URL - Any publicly accessible JSON endpoint

For GitHub-hosted projects:

html_context = {
    "version_switcher_url": "https://raw.githubusercontent.com/org/repo/main/docs/_static/switcher.json",
}

Styling#

Customize the switcher appearance:

:root {
  --bz-version-switcher-color: var(--bz-color-muted);
  --bz-version-switcher-border-color: var(--bz-color-outline);
  --bz-version-switcher-border-color-hover: var(--bz-color-primary);
  --bz-version-switcher-background-color: var(--bz-color-surface-2);
  --bz-version-switcher-font-size: var(--bz-size-xs);
  --bz-version-switcher-font-family: inherit;
}