Performance Benchmarks

Measured build times for Bengal using the benchmark suite in the repository.

Test Methodology

Test Content Characteristics

The benchmark suite uses minimal test pages:

• Simple Markdown with YAML frontmatter
• No directives (no::: blocks, no {eval-rst})
• No syntax highlighting
• No table of contents generation
• Basic theme with navigation and footer

Important: Real-world sites with directives, syntax highlighting, and complex templates build slower than these benchmarks suggest. See What Slows Builds Down for factors that affect your actual build times.

Build Performance by Site Size

Cold build times (no cache) for the benchmark test content.

These numbers represent best-case performance with minimal content. Your results will vary based on content complexity.

Incremental Build Performance

Time to rebuild when one file changes (warm cache).

Incremental builds provide the largest real-world benefit. Even on large sites, editing a single page rebuilds in under 100 ms.

Memory Usage

Peak RAM during builds with benchmark test content.

Memory per page decreases at scale due to shared overhead (theme, templates, configuration).

Parallel Processing

Build performance with different worker counts (1,000 pages).

Diminishing returns above 4-8 workers due to I/O bottlenecks and coordination overhead.

Free-Threaded Python Impact

Comparing Python 3.14 with and without the GIL (1,000 pages).

# Enable free-threading
PYTHON_GIL=0 bengal build

Kida Template Engine Advantage

Bengal uses Kida for template rendering. Under concurrent workloads, Kida significantly outperforms Jinja2:

This advantage comes from Kida's thread-safe design (copy-on-write updates, local render state, GIL independence). Jinja2 shows negative scaling at high concurrency due to internal contention.

What Slows Builds Down

Real-world sites build slower than benchmarks. Common factors:

Real-World Example: Bengal Documentation Site

The Bengal documentation site itself (the site you're reading) shows how incremental builds behave on directive-heavy content:

✓ Built 803 pages in 3.19 s (incremental+parallel) | 252.0 pages/sec  # warm caches
✓ Built 803 pages in 6.49 s (incremental+parallel) | 123.6 pages/sec  # cold caches

Even with warm caches, real documentation sites with directive-heavy content show variable performance. The docs use:

• Syntax-highlighted code blocks throughout
• Admonition directives (:::note, :::warning, etc.)
• Tab containers and card grids
• Table of contents on most pages
• Cross-references and backlinks

Realistic Expectations

These are render-light/warm-cache upper bounds, not the committed ~18–20 pages/s end-to-end baseline. Your results depend on content complexity; directive-heavy documentation sites typically see 40-60% of these render-light figures.

Running Benchmarks

Run the benchmark suite yourself from the repository:

cd benchmarks

# Install dependencies
pip install -r requirements.txt

# Also install bengal in editable mode from project root
pip install -e ..

# Run all benchmarks (from project root)
poe benchmark

# Or with pytest directly
pytest benchmarks/ tests/performance/ -v --benchmark-only

# Run specific benchmark
pytest tests/performance/ -k "incremental" -v --benchmark-only

# Save and compare results
poe benchmark-save
poe benchmark-compare

Available Benchmark Suites

Performance Tips

1. Use incremental builds during development:bengal build --incremental
2. Enable fast mode:bengal build --fast(quiet output, max speed)
3. Enable template caching: Setcache_templates = truein config (default)
4. Use free-threaded Python:PYTHON_GIL=0with Python 3.14+
5. Minimize directives: Each directive adds parsing and rendering overhead