Configure Bengal

Bengal supports TOML, YAML, and directory-based configuration files.

Configuration Structure

Bengal configuration follows a Three-Layer Architecture to separate concerns:

1. site (Identity & Metadata)

   • Who you are: title, author, baseurl
   • Structure: menus, taxonomies
   • Does NOT control content processing.

2. content (Processing Pipeline)

   • How Bengal computes content: excerpts, reading time, TOC depth
   • This is the API that themes rely on.
   • Why separate this? It allows you to switch themes without breaking your content model or SEO metadata. The theme just displays what Bengal computed.

3. params (User Variables)

   • Custom site-specific data
   • Accessible in templates as{{ site.config.params.foo }}

File Formats & Locations

Bengal looks for configuration in the following order:

1. bengal.toml(Recommended for simple sites)
2. bengal.yaml/bengal.yml
3. config.toml
4. config.yaml/config.yml
5. config/directory (Recommended for complex sites)

Directory-Based Config

For larger sites, you can split configuration into multiple files:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

config/
├── _default/
│   ├── site.yaml      # Identity: title, author, menus
│   ├── content.yaml   # Processing: excerpt_length, sorting
│   ├── params.yaml    # Custom variables
│   ├── build.yaml     # Build settings
│   └── features.yaml  # Feature flags
├── environments/
│   ├── local.yaml     # Dev overrides
│   └── production.yaml # Prod overrides

Reference

[site]

General site identity and metadata.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

[site]
title = "My Site"
description = "A Bengal SSG site"
baseurl = "https://example.com"
language = "en"
author = "Your Name"

[site.taxonomies]
tags = "tags"
categories = "categories"

[[site.menu.main]]
name = "Home"
url = "/"
weight = 1

[content]

Controls how Bengal processes and organizes content.

[markdown]

Configure the Markdown parsing engine.

1
2

[markdown]
parser = "mistune"       # "mistune" (fast, default) or "python-markdown" (full-featured)

Note:mistuneis significantly faster (2-5x) and recommended for most sites. Usepython-markdownonly if you rely on specific Python-Markdown extensions.

[build]

Build process settings.

1
2
3
4
5
6

[build]
output_dir = "public"
parallel = true          # Enable parallel processing
incremental = false      # Enable incremental builds
max_workers = null       # Auto-detect based on CPU cores (default: CPU count - 1, min 4)
pretty_urls = true       # Generate /page/index.html instead of /page.html

Note:max_workersdefaults to auto-detection based on your CPU cores (leaves 1 core for OS, minimum 4 workers). Set a specific number to override.

[assets]

Asset pipeline configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[assets]
minify = true            # Minify CSS/JS
optimize = true          # Optimize images
fingerprint = true       # Add cache-busting hashes (style.abc123.css)
pipeline = false         # Enable Node.js asset pipeline (optional)

[assets.images]
quality = 85             # JPEG quality
strip_metadata = true    # Remove EXIF data
formats = ["webp"]       # Generate additional formats

[output_formats]

Configure alternative output formats (JSON, LLM text).

1
2
3
4
5
6
7
8

[output_formats]
enabled = true
per_page = ["json", "llm_txt"]
site_wide = ["index_json", "llm_full"]

[output_formats.options]
include_html_content = true
json_indent = 2

[params]

Arbitrary user parameters.

1
2
3
4

[params]
product_name = "Bengal"
analytics_id = "UA-12345-6"
social_twitter = "@bengal_ssg"