Enable Multi-Version Documentation

Add a version selector to your documentation site so users can switch between releases.

This recipe walks you through enabling versioned documentation for a project with two existing releases (0.1 and 0.2) and a development version.

1. Declare Your Versions

Add a versions list to your great-docs.yml:

great-docs.yml
versions:
  - label: "0.3.0 (dev)"
    tag: dev
    prerelease: true
  - label: "0.2.0"
    tag: "0.2"
    latest: true
  - label: "0.1.0"
    tag: "0.1"

Order versions newest-first. The version marked latest: true becomes the canonical version served at the site root.

2. Snapshot Older Versions’ APIs

The current version (dev) uses live API introspection. For released versions, create API snapshots so the build can generate accurate reference pages without needing the old source code:

Terminal
great-docs api-snapshot --output api-snapshots/0.2.json

Check out the 0.1 tag and do the same:

Terminal
git stash
git checkout v0.1.0
great-docs api-snapshot --output api-snapshots/0.1.json
git checkout main
git stash pop

Then reference the snapshots in your config:

great-docs.yml
versions:
  - label: "0.3.0 (dev)"
    tag: dev
    prerelease: true
  - label: "0.2.0"
    tag: "0.2"
    latest: true
    api_snapshot: api-snapshots/0.2.json
  - label: "0.1.0"
    tag: "0.1"
    api_snapshot: api-snapshots/0.1.json
Tip

Alternatively, use git_ref to let Great Docs introspect the package at a Git tag automatically:

  - label: "0.1.0"
    tag: "0.1"
    git_ref: v0.1.0

3. Build

Terminal
great-docs build

This produces a site with:

  • / — version 0.2 (the latest)
  • /v/dev/ — the development version
  • /v/0.1/ — version 0.1

A version selector dropdown appears in the navbar.

4. Add Version-Specific Content (Optional)

Mark content that only applies to certain versions:

user_guide/getting-started.qmd
::: {.version-only versions=">=0.2"}
## New Configuration Format

Starting in 0.2, configuration uses YAML instead of TOML.
:::

Or scope an entire page to specific versions using frontmatter:

user_guide/migration.qmd
---
title: "Migrating from 0.1 to 0.2"
versions: ["0.2", "dev"]
---

5. Iterate Quickly

During development, build only the latest version for faster iteration:

Terminal
great-docs build --latest-only

When you’re ready to publish, run a full build to generate all versions.

6. Mark End-of-Life Versions

When you drop support for a version, add eol: true:

great-docs.yml
  - label: "0.1.0"
    tag: "0.1"
    eol: true
    api_snapshot: api-snapshots/0.1.json

Visitors viewing 0.1 will see a warning banner encouraging them to upgrade.

Result

Your site now has:

  • A version selector in the navbar for switching between versions
  • Warning banners on non-latest versions
  • Floating aliases at /v/latest/ and /v/stable/
  • Per-version API reference pages generated from snapshots
  • Smart fallback navigation — switching to a version that lacks the current page lands on the section index instead of a 404