Configuration - Bengal

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

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

# 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

# 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

[assets]
minify = true
optimize = true
fingerprint = true

Template Validation

Enablevalidate_templatesto catch template syntax errors early during builds:

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

[build]
validate_templates = true

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

[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.