Versioned Documentation

Serve multiple versions of your documentation from a single site

3 min read 639 words

Bengal supports versioned documentation, allowing you to maintain multiple versions of your docs (e.g., v1, v2, v3) and let users switch between them.

Why Version Your Docs?

  • API libraries: Users on older versions need docs that match their installed version
  • Breaking changes: Major releases often have different APIs or workflows
  • Enterprise support: Some users stay on LTS versions for years
  • Migration guides: Link between versions to help users upgrade

Two Modes

Bengal supports two versioning modes:

Folder Mode (Default)

Store versions in_versions/directories:

content/
├── docs/              # Latest version (v3)
│   └── guide.md
└── _versions/
    ├── v2/
    │   └── docs/
    │       └── guide.md
    └── v1/
        └── docs/
            └── guide.md

Best for: Most projects, simple setup, easy to understand.

→ Set up Folder Mode

Git Mode

Build from Git branches or tags:

versioning:
  mode: git
  git:
    branches:
      - name: main
        latest: true
      - pattern: "release/*"
        strip_prefix: "release/"

Best for: Projects that already use release branches, CI/CD pipelines.

→ Set up Git Mode

Quick Start (Folder Mode)

1. Enable Versioning

# bengal.yaml
versioning:
  enabled: true
  versions:
    - id: v3
      latest: true
    - id: v2
    - id: v1
  sections:
    - docs

2. Create a Version Snapshot

# Snapshot current docs as v2 before making breaking changes
bengal version create v2

This copiesdocs/→_versions/v2/docs/.

3. Build

bengal build

Your site now has:

  • /docs/guide/→ v3 (latest)
  • /docs/v2/guide/→ v2
  • /docs/v1/guide/→ v1

URL Structure

Version URL Pattern Example
Latest /docs/page/ /docs/installation/
Older /docs/{version}/page/ /docs/v2/installation/

The latest version has no version prefix in URLs—cleaner for most users.

Features

Version Selector

A dropdown appears in the documentation sidebar when versioning is enabled, letting users switch between versions. Bengal's version selector includes smart fallback: if a page doesn't exist in the target version, it navigates to the nearest equivalent (section index or version root) instead of showing a 404.

The default theme includes the version selector automatically. To customize, overridepartials/version-selector.htmlin your theme.

Version Banners

Older versions automatically display a warning banner linking to the latest docs. Customize the banner per version:

versions:
  - id: v2
    banner:
      type: warning  # or: info, danger
      message: "You're viewing docs for v2. See the latest version."

Banner types:info(blue),warning(yellow),danger(red for deprecated versions).

Link to specific versions from any page:

See the [[v2:docs/migration|v2 Migration Guide]] for upgrade steps.

→ Cross-Version Linking

Version Directives

Mark when features were added, deprecated, or changed:

:::{since} v2.0
This feature was added in version 2.0.
:::

:::{deprecated} v3.0
Use `new_function()` instead.
:::

:::{changed} v2.5
Default timeout changed from 30s to 60s.
:::

→ Version Directives

SEO Optimization

Bengal automatically handles SEO for versioned docs:

  • Canonical URLs: Older versions point to latest version (prevents duplicate content penalties)
  • Sitemap priorities: Latest version pages get priority 0.8; older versions get 0.3
  • No-index option: Mark deprecated versions asnoindexto remove from search entirely

CLI Commands

# List all versions
bengal version list

# List versions as JSON (for scripting)
bengal version list --format json

# Show version details
bengal version info v2

# Create a new version snapshot
bengal version create v2 --label "2.0 LTS"

# Preview what create would do
bengal version create v2 --dry-run

# Compare versions
bengal version diff v2 v3

# Compare git branches directly
bengal version diff main release/0.1.6 --git

Next Steps