Multi-Variant Builds

Build different site variants (OSS vs Enterprise, brand1 vs brand2) from one content tree

3 min read 501 words

Build multiple documentation sites from a single content tree. Use this when you have:

  • OSS vs Enterprise — Open-source docs plus paid-feature docs
  • Brand variants — Same content, different branding or feature sets
  • Acquired products — Merged doc sites with edition-specific pages

How It Works

  1. Frontmatter: Addeditionto pages that belong to specific variants.
  2. Config: Setparams.editionper environment to select the variant.
  3. Build: Bengal filters out pages whoseeditiondoes not include the selected variant.

Pages withouteditionare included in all builds.

Frontmatter

Useeditionin page frontmatter:

# Shared page — included in every build
---
title: Getting Started
---

# Getting Started

Welcome to the docs.

# Enterprise-only page
---
title: SSO Configuration
edition: [enterprise]
---

# SSO Configuration

Configure single sign-on for your organization.

# OSS and Enterprise (both variants)
---
title: API Reference
edition: [oss, enterprise]
---

# API Reference

Full API documentation.

Accepted formats:

Format Result
edition: [enterprise] Page only inenterprisebuilds
edition: [oss, enterprise] Page in bothoss and enterprisebuilds
edition: enterprise Normalized to[enterprise]
Omitedition Page in all builds

Configuration

Setparams.editionin your environment config:

# config/environments/oss.yaml
params:
  edition: oss

site:
  baseurl: "https://docs.example.com"

# config/environments/enterprise.yaml
params:
  edition: enterprise

site:
  baseurl: "https://enterprise.example.com"

Environment Variable Override

Override viaBENGALxPARAMSxEDITION:

BENGALxPARAMSxEDITION=enterprise bengal build --environment production

This follows Bengal's standard env override pattern: BENGALx + key path with xas delimiter.

Build Commands

# OSS site
bengal build --environment oss

# Enterprise site
bengal build --environment enterprise

# Or via env var
BENGALxPARAMSxEDITION=enterprise bengal build --environment production

Content Organization

Typical structure:

content/
├── _index.md              # Shared landing
├── getting-started/
│   ├── _index.md          # Shared
│   ├── install.md         # Shared
│   └── quickstart.md      # Shared
├── api/
│   ├── _index.md          # Shared
│   └── reference.md       # edition: [oss, enterprise]
├── enterprise/
│   ├── _index.md          # edition: [enterprise]
│   ├── sso.md             # edition: [enterprise]
│   └── audit-logs.md      # edition: [enterprise]
└── oss/
    └── contributing.md    # edition: [oss]

Cascade

Use cascade to applyeditionto entire sections:

---
# content/enterprise/_index.md
title: Enterprise
edition: [enterprise]
cascade:
  edition: [enterprise]
---

Child pages inherit editionfrom cascade unless they override it.

CI/CD

Build both variants in separate jobs:

jobs:
  build-oss:
    steps:
      - run: bengal build --environment oss
      - uses: actions/upload-artifact@v4
        with:
          name: site-oss
          path: public/

  build-enterprise:
    steps:
      - run: bengal build --environment enterprise
      - uses: actions/upload-artifact@v4
        with:
          name: site-enterprise
          path: public/

Or use a matrix:

jobs:
  build:
    strategy:
      matrix:
        edition: [oss, enterprise]
    steps:
      - run: bengal build --environment ${{ matrix.edition }}
      - uses: actions/upload-artifact@v4
        with:
          name: site-${{ matrix.edition }}
          path: public/

See Also