# Configuration

URL: /docs/building/configuration/
Section: configuration

--------------------------------------------------------------------------------

Configuration Control Bengal's behavior through bengal.toml and 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 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 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 Single File Directory-Based 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 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 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 Enable validate_templates to 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. Development CI/CD 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 Note Template validation adds a small overhead to build time. For large sites, consider enabling it only in development and CI environments.

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 418
- Reading Time: 2 minutes