# Folder Mode Setup

URL: /docs/content/versioning/folder-mode/
Section: versioning

--------------------------------------------------------------------------------

Folder Mode Setup 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 │ └── ... Step 1: Enable Versioning Add to your bengal.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"]. Step 2: Create Version Directories Option A: Use the CLI (Recommended) # 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/ Step 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. Snapshot Current Docs # Create v2 from current docs bengal version create v2 --label "2.0" 2. Update Configuration versions: - id: v3 # NEW: will be the latest latest: true - id: v2 # Previous latest - id: v1 3. Make Breaking Changes Edit content/docs/ freely—v2 is preserved in _versions/v2/docs/. 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 that the version is listed in bengal.yaml Verify the directory exists: _versions/{id}/docs/ Ensure content exists in the version directory Wrong Version Showing as Latest Only one version should have latest: true: versions: - id: v3 latest: true # ✓ Only this one - id: v2 # latest: true # ✗ Remove this URLs Incorrect Check sections in your config matches your content structure: sections: - docs # Must match your content/docs/ directory Next Steps Cross-Version Links — Link between versions Version Directives — Mark version-specific content Git Mode — Alternative: build from branches

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 621
- Reading Time: 3 minutes