Folder Mode Setup

Set up versioned documentation using folder-based versioning

4 min read 706 words

Folder mode is the simplest way to version your documentation. Each version lives in its own directory.

Directory Structure

your-site/
├── bengal.yaml
├── content/
│   ├── docs/                    # Latest version (v3)
│   │   ├── _index.md
│   │   ├── installation.md
│   │   └── guide/
│   │       └── getting-started.md
│   └── _versions/
│       ├── v2/
│       │   └── docs/            # v2 content
│       │       ├── _index.md
│       │       ├── installation.md
│       │       └── guide/
│       │           └── getting-started.md
│       └── v1/
│           └── docs/            # v1 content
│               └── ...
  1. 1

    Enable Versioning

    Add to yourbengal.yaml:

    versioning:
  enabled: true
  versions:
    - id: v3
      label: "3.0"
      latest: true
    - id: v2
      label: "2.0"
    - id: v1
      label: "1.0"
      deprecated: true
  sections:
    - docs  # Which content sections are versioned (default)

    If you omit sections, it defaults to ["docs"].

  2. 2

    Create Version Directories

    # Before making breaking changes, snapshot current docs
bengal version create v2

# This creates _versions/v2/docs/ with a copy of docs/

    Option B: Create Manually

    mkdir -p content/_versions/v2/docs
cp -r content/docs/* content/_versions/v2/docs/
  3. 3

    Build and Verify

    bengal build

    Check the output:

    public/
├── docs/
│   ├── index.html              # /docs/ (latest)
│   └── installation/
│       └── index.html          # /docs/installation/
├── docs/v2/
│   ├── index.html              # /docs/v2/
│   └── installation/
│       └── index.html          # /docs/v2/installation/
└── docs/v1/
    └── ...

Configuration Options

Full Configuration Reference

versioning:
  enabled: true

  # Version definitions
  versions:
    - id: v3                    # Required: unique identifier
      label: "3.0 (Current)"    # Optional: display label
      latest: true              # One version must be latest

    - id: v2
      label: "2.0 LTS"
      banner:                   # Optional: warning banner
        type: warning           # info, warning, or danger
        message: "This is an older version. See v3 for latest."
        show_latest_link: true

    - id: v1
      label: "1.0"
      deprecated: true          # Marks version as deprecated
      end_of_life: "2024-12-31" # Optional: EOL date

  # Aliases for version IDs
  aliases:
    latest: v3
    stable: v3
    lts: v2

  # Which sections are versioned (default: ["docs"])
  sections:
    - docs
    # - api    # Add more if needed

  # Shared content across all versions (default: ["_shared"])
  shared:
    - _shared  # Content in _shared/ appears in all versions

Shared Content

Content that should appear in all versions goes in_shared/:

content/
├── docs/
├── _versions/
└── _shared/
    └── docs/
        └── changelog.md    # Appears in all versions

Workflow: Creating a New Version

When you're about to release a breaking change:

  1. 1

    Snapshot current docs

    # Create v2 from current docs
bengal version create v2 --label "2.0"
  2. 2

    Update configuration

    versions:
  - id: v3          # NEW: will be the latest
    latest: true
  - id: v2          # Previous latest
  - id: v1
  3. 3

    Make breaking changes

    Editcontent/docs/ freely—v2 is preserved in _versions/v2/docs/.

  4. 4

    Build and deploy

    bengal build

Tips

Keep Versions in Sync

For pages that exist in all versions (like changelog), use shared content:

_shared/docs/changelog.md

Mark Deprecated Versions

versions:
  - id: v1
    deprecated: true
    banner:
      type: danger
      message: "v1 is no longer supported. Please upgrade to v3."

Version-Specific Banners

Each version can have its own banner:

versions:
  - id: v2
    banner:
      type: info
      message: "v2 is in LTS. Security updates until 2025."

Troubleshooting

Version Not Appearing

Check version is listed

Verify the version is listed inbengal.yaml under versions.

Verify directory exists

Ensure_versions/{id}/docs/exists for your version id.

Ensure content exists

Confirm the version directory contains content files.

Wrong Version Showing as Latest

Only one version should havelatest: true:

versions:
  - id: v3
    latest: true    # ✓ Only this one
  - id: v2
    # latest: true  # ✗ Remove this

URLs Incorrect

Checksectionsin your config matches your content structure:

sections:
  - docs    # Must match your content/docs/ directory

Next Steps