# Configuration

URL: /bengal/docs/ship/configuration/
Section: configuration
Description: Configuring Bengal with bengal.toml

---

> For a complete page index, fetch /bengal/llms.txt.

Configure builds, environments, themes, and site metadata before you ship.

Note

Do I need this? Yes when tuning production builds, multi-environment setups, or
theme selection. Skip on day one —`bengal new site`scaffolds sensible defaults.

Build Profiles

Configure Bengal for different workflows with built-in profiles

(/bengal/docs/ship/configuration/profiles/)

Multi-Variant Builds

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

(/bengal/docs/ship/configuration/variants/)

Configuration Reference

Complete reference of all bengal.toml options

(/bengal/docs/ship/configuration/reference/)

Runtime Capabilities

Enable self-hosted diagram, math, and third-party JS capabilities

(/bengal/docs/ship/configuration/capabilities/)

## 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 the`config/` directory (preferred) OR `bengal.toml` (legacy/simple). If `config/` exists, `bengal.toml`is ignored.

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

## Quick Start

toml
TOML

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

[build]
output_dir = "public"

[theme]
name = "default"
```
## Configuration Patterns

- Single File (#)

- Directory-Based (#)

Best for small sites:

toml
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
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
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 in`bengal.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-incremental`CLI 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
TOML

```
[assets]
minify = true
optimize = true
fingerprint = true
```
### Template Validation

Enable`validate_templates`to catch template syntax errors early during builds:

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

- Development (#)

- CI/CD (#)

Enable template validation during development for immediate feedback:

toml
TOML

```
[build]
validate_templates = true
```

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

toml
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 (https://lbliii.github.io/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-security`runs Kida's static escape
and privacy analysis. It reports trust-boundary warnings such as unexplained
`| safe`use and sensitive-looking context paths without failing the check unless
Kida reports an error-level finding.

`bengal check --templates-context`also uses Kida's dotted-path context contract
checker. It can catch missing nested context such as`page.title`while treating
dynamic customization roots like`params.*` 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
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. Set`params.edition` per environment and add `edition`to page frontmatter to filter content.

Seealso

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

## In This Section

Build Profiles (/bengal/docs/ship/configuration/profiles/)

Configure Bengal for different workflows with built-in profiles

Configuration Reference (/bengal/docs/ship/configuration/reference/)

Complete reference of all bengal.toml options

Multi-Variant Builds (/bengal/docs/ship/configuration/variants/)

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

Runtime Capabilities (/bengal/docs/ship/configuration/capabilities/)

Enable self-hosted diagram, math, and third-party JS capabilities

Related Pages

Internationalization (i18n) (/bengal/docs/build-sites/structure/i18n/)

Multi-language sites with gettext PO/MO, RTL support, and translation workflows

Related

Ship (/bengal/docs/ship/)

Build configuration, SEO/discovery, output formats, and deployment

Related

Analysis (/bengal/docs/build-sites/structure/analysis/)

Site structure analysis tools

Related

Versioned Documentation (/bengal/docs/build-sites/structure/versioning/)

Serve multiple versions of your documentation from a single site

Related

persona-operator (/bengal/tags/persona-operator/)