Folder Mode Setup

Set up versioned documentation using folder-based versioning

4 min read 716 words
Edit this page

Was this page helpful?

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

Directory Structure

TREE-SITTER-QUERY
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:

    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

    BASH
    # 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

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

    Build and Verify

    BASH
    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

YAML
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"
      status: deprecated        # current, legacy, deprecated, preview, or eol
      deprecated: true          # Backward-compatible alias for status: 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/:

TREE-SITTER-QUERY
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

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

    Update configuration

    YAML
    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

    BASH
    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

YAML
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:

YAML
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:

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

URLs Incorrect

Checksectionsin your config matches your content structure:

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

Next Steps