Configuration

Configuring Bengal with bengal.toml

1 page in this section

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) ORbengal.toml(legacy/simple). Ifconfig/exists,bengal.tomlis ignored.

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

Quick Start

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# bengal.toml
[site]
title = "My Site"
base_url = "https://example.com"
language = "en"

[build]
output_dir = "public"
clean = true

[theme]
name = "default"

Configuration Patterns

Best for small sites:

1
2
3
4
5
6
7
8
9
# bengal.toml - everything in one place
[site]
title = "My Blog"

[build]
output_dir = "public"

[theme]
name = "default"

Best for larger sites:

config/
├── _default/
│   ├── site.yaml
│   ├── build.yaml
│   └── theme.yaml
└── environments/
    ├── production.yaml
    └── staging.yaml

Environment Overrides

Run with different settings per environment:

bengal build --environment production

1
2
3
4
5
6
7
# config/environments/production.yaml
site:
  base_url: "https://example.com"

build:
  minify: true
  fingerprint: true

Tip

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

Build Options Reference

Key[build]configuration options:

Option Type Default Description
output_dir string "public" Directory for generated files
clean bool false Remove output directory before build
minify bool false Minify HTML/CSS/JS output
fingerprint bool false Add content hash to asset URLs
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

Template Validation

Enablevalidate_templatesto catch template syntax errors early during builds:

1
2
[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:

1
2
[build]
validate_templates = true

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

1
2
3
[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:

  • Jinja2 syntax errors (unclosed tags, invalid filters)
  • 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.