# Configuration URL: /bengal/docs/ship/configuration/ Section: configuration Tags: persona-operator -------------------------------------------------------------------------------- Configuration Configure builds, environments, themes, and site metadata before you ship. Note 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. User 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 Configuration Reference Complete reference of all bengal.toml options File Runtime Capabilities Enable self-hosted diagram, math, and third-party JS 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 # 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: # 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 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 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 [assets] minify = true optimize = true fingerprint = true Template Validation Enable validate_templates to 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. Development CI/CD 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 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: [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. Info Seealso Multi-Variant Builds — Full guide for OSS/Enterprise and brand variants -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 687 - Reading Time: 3 minutes