Configuration

Configuring Bengal with bengal.toml

4 min read 724 words
Edit this page

Was this page helpful?

Control Bengal's behavior throughbengal.tomland environment-specific settings.

Configuration Methods

flowchart TB subgraph "Base Configuration (Mutually Exclusive)" A[bengal.toml] B[config/ directory] end C[Environment Overrides] D[CLI Flags] E[Final Config] A -.->|OR| E B -.->|OR| E C --> E D --> E

Bengal loads configuration from either theconfig/ directory (preferred) OR bengal.toml (legacy/simple). If config/ exists, bengal.tomlis ignored.

Overrides apply in order: Base Config → Environment Overrides → CLI Flags.

Quick Start

TOML
# bengal.toml
[site]
title = "My Site"
baseurl = "https://example.com"
language = "en"

[build]
output_dir = "public"

[theme]
name = "default"

Configuration Patterns

Best for small sites:

TOML
# bengal.toml - everything in one place
[site]
title = "My Blog"

[build]
output_dir = "public"

[theme]
name = "default"

Best for larger sites:

TREE-SITTER-QUERY
config/
├── _default/
│   ├── site.yaml
│   ├── build.yaml
│   └── theme.yaml
└── environments/
    ├── production.yaml
    └── staging.yaml

Environment Overrides

Run with different settings per environment:

BASH
bengal build --environment production
YAML
# config/environments/production.yaml
site:
  baseurl: "https://example.com"

build:
  minify_html: true
  strict_mode: true

assets:
  fingerprint: true

Tip

Best practice: Keep development settings inbengal.toml, add production overrides in config/environments/production.yaml.

Build Options Reference

Key[build]configuration options:

Option Type Default Description
output_dir string "public" Directory for generated files
minify_html bool true Minify HTML output
validate_templates bool false Proactive template syntax validation
validate_build bool true Post-build validation checks
validate_links bool true Check for broken internal links
strict_mode bool false Fail build on any error or warning
fast_mode bool false Enable maximum performance optimizations

Note

Incremental builds are automatic. First build is full (creates cache), subsequent builds only rebuild changed content. Use--no-incrementalCLI flag for debugging or CI clean builds.

Asset Options

Configure asset processing in the[assets]section:

Option Type Default Description
minify bool true Minify CSS/JS assets
optimize bool true Optimize images
fingerprint bool true Add content hash to asset URLs
TOML
[assets]
minify = true
optimize = true
fingerprint = true

Template Validation

Enablevalidate_templatesto catch template syntax errors early during builds:

TOML
[build]
validate_templates = true

When enabled, Bengal validates all templates (HTML/XML) in your template directories before rendering. This provides early feedback on syntax errors, even for templates that might not be used by every page.

Enable template validation during development for immediate feedback:

TOML
[build]
validate_templates = true

Combine with strict mode in CI pipelines to fail builds on template errors:

TOML
[build]
validate_templates = true
strict_mode = true

When to enable:

  • During active theme development
  • In CI/CD pipelines
  • When debugging template issues

What it catches:

  • Template syntax errors (unclosed tags, invalid filters) in Kida and Jinja2
  • Unknown filter names
  • Template assertion errors

Note

Template validation adds a small overhead to build time. For large sites, consider enabling it only in development and CI environments.

For Kida templates,bengal check --templates-securityruns Kida's static escape and privacy analysis. It reports trust-boundary warnings such as unexplained | safeuse and sensitive-looking context paths without failing the check unless Kida reports an error-level finding.

bengal check --templates-contextalso uses Kida's dotted-path context contract checker. It can catch missing nested context such aspage.titlewhile treating dynamic customization roots likeparams.* and site.data.*as author-provided data.

Kida Options

Kida-specific options live under[kida] in bengal.toml or kida:in YAML config files.template_aliases maps @alias/prefixes to paths relative to the active template roots:

TOML
[kida]
bytecode_cache = true
static_context = false

[kida.template_aliases]
components = "ui/components"

Templates can then include shared files with {% include "@components/card.html" %}.

Multi-Variant Builds

Build different site variants (OSS vs Enterprise, brand1 vs brand2) from one content tree. Setparams.edition per environment and add editionto page frontmatter to filter content.

Seealso

Multi-Variant Builds — Full guide for OSS/Enterprise and brand variants

In This Section

Build Profiles Configure Bengal for different workflows with built-in profiles
Multi-Variant Builds Build different site variants (OSS vs Enterprise, brand1 vs brand2) from one content tree