Versioned Documentation

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

Modes and Behaviors

Bengal supports folder snapshots and Git-backed builds. Git mode can either use explicit branch/tag patterns or select recent release tags automatically.

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

Git mode can also track the latest branch plus recent release tags:

versioning:
  enabled: true
  mode: git
  git:
    latest:
      branch: main
      id: main
      label: Latest
    previous:
      source: tags
      count: 3
      pattern: "v*"
      strip_prefix: "v"
      sort: semver-desc
      include_prereleases: false

With tags v0.3.2, v0.3.1, and v0.3.0, this builds /docs/from main plus /docs/0.3.2/, /docs/0.3.1/, and /docs/0.3.0/. You can also writesource: releases/tagsif that wording better matches your release process; Bengal still reads Git tags, not the GitHub Releases API.

When the selected tag set changes,bengal build --all-versionsremoves stale version directories it previously managed so old docs do not linger after count, pattern, or prerelease settings change.

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 copies docs/ → _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

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
    status: legacy
    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). Version status can becurrent, legacy, deprecated, preview, or eol. The olderdeprecated: true key still works and is treated like status: deprecated.

Cross-Version Links

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

Build Artifacts (versions.json)

When versioning is enabled, Bengal emitsversions.jsonat the output root. This Mike-compatible manifest lists all versions with titles, aliases, and URL prefixes—useful for custom themes or external tools.

[
  {"version": "v3", "title": "3.0", "aliases": ["latest"], "url_prefix": ""},
  {"version": "v2", "title": "2.0", "aliases": [], "url_prefix": "/v2"}
]

Disable with versioning.emit_versions_json: false.

Root Redirect

For docs-only sites where the root should redirect to the default version:

versioning:
  enabled: true
  default_redirect: true
  default_redirect_target: "/docs/"  # optional, defaults to first section

This writes index.htmlat the output root with a meta-refresh and JavaScript redirect. Note: This overwrites any existing home page—use only when the site root is meant to redirect to docs.

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 --old-version main --new-version release/0.1.6 --git

Next Steps

• Folder Mode Setup — Step-by-step guide
• Git Mode Setup — Build from branches
• Cross-Version Links — Link between versions
• Version Directives — Mark version-specific content