Bengal 0.1.3

Performance, stability, theme enhancements, and critical bug fixes

Released: October 20, 2025

This release focuses on performance optimization, a new "fast mode" for maximum build speed, and significant code quality improvements.

🚀 Fast Mode (NEW!)

Introducing Fast Mode - a new build mode optimized for maximum speed with minimal output.

1
2
3
4
5
6
# Enable via CLI
bengal site build --fast

# Or in your bengal.toml
[build]
fast_mode = true

What Fast Mode does:

  • Enables quiet output (minimal logging overhead)
  • Ensures parallel rendering is enabled
  • Perfect for CI/CD pipelines and benchmarking
  • Combine withPYTHON_GIL=0to suppress warnings in Python 3.14t

When to use it:

  • Production builds in CI/CD
  • Benchmarking and performance testing
  • Large sites where you don't need detailed output
  • Showing off Bengal's speed 😊

⚡ Performance Improvements

Page List Caching

75% reduction in page equality checks on large sites.

  • Added cached properties:Site.regular_pagesandSite.generated_pages
  • Reduced equality checks from 446K → 112K at 400 pages
  • All orchestration code updated to use cached properties
  • Eliminates repeated O(n) filtering during builds

Impact: Faster builds across the board, especially on sites with 100+ pages.

Related posts computation now uses parallel processing for large sites.

Before: 120 seconds (10k pages, Python 3.14t) After: 16 seconds (10k pages, Python 3.14t) Speedup: 7.5x faster

  • Automatically enabled for sites with 100+ pages
  • Uses your site'smax_workersconfiguration
  • Also benefits Python 3.13 (2.4-3x faster)

Parallel Taxonomy Generation

Tag page generation now uses parallel processing.

Before: 24 seconds (10k pages, 800 tags, Python 3.14t) After: 4 seconds (10k pages, 800 tags, Python 3.14t) Speedup: 6x faster

  • Automatically enabled for sites with 20+ tags
  • Also benefits Python 3.13 (2-3x faster)

Combined savings: ~2 minutes saved on large site builds with Python 3.14t.

🐛 Bug Fixes

🔥 CRITICAL: Incremental Build Non-Determinism

Fixed: Major bug where incremental and full builds produced different HTML output, violating the core SSG contract.

This was a critical issue affecting the reliability of incremental builds. When building incrementally, the output could differ from a full build, leading to inconsistent results.

Root causes fixed:

  1. PageProxy missingpermalinkproperty → broken navigation links
  2. PageProxy missing_sitereference → couldn't resolve baseurl
  3. PageProxy missingoutput_path→ postprocessing skipped cached pages
  4. Stale PageProxy objects during postprocessing → old content in output
  5. Navigation cross-dependencies not tracked → adjacent pages not rebuilt

Impact: Incremental builds now produce byte-identical output to full builds. This fix ensures that Bengal's incremental caching is trustworthy and reliable.

PageProxy Template Compatibility

Fixed: Template errors when using PageProxy objects in incremental builds.

The error'PageProxy' object has no attribute 'meta_description'no longer occurs. PageProxy now has all the properties that templates expect:

  • Computed properties:meta_description,reading_time,excerpt
  • Metadata properties:is_home,is_section,is_page,kind,description,draft,keywords
  • Setter forrendered_htmlto support rendering phase

Autodoc CLI Template Selection

Fixed: CLI command documentation pages now render with proper sidebar navigation.

Changed autodoc to settype: cli-referenceinstead oftype: cli-command, ensuring individual CLI command pages use the correct template with full documentation layout.

Incremental Build Regression

Fixed: Critical error blocking incremental rebuilds on second and subsequent runs.

The error'str' object has no attribute 'path'has been resolved. PageProxy now correctly handles section metadata stored as string paths rather than Section objects.

PageProxy Navigation Properties

Fixed: Missing navigation properties causing template rendering errors.

The error'PageProxy' object has no attribute 'prev_in_section'(andnext_in_section) has been resolved. PageProxy now includes all navigation properties that templates expect:

  • next_in_section- Navigate to the next page in the same section
  • prev_in_section- Navigate to the previous page in the same section

This ensures documentation navigation works correctly in incremental builds.

Unrendered Jinja2 Markers

Fixed: Jinja2 markers ({{ }}and{% %}) no longer leak into HTML whenpreprocess: false.

Added proper escaping and hardened the Mistune path to restore placeholders as entities.

Incremental Cache False Positives

Fixed: Config file hash now recorded correctly after full builds, preventing false cache hits.

🎨 CLI & Theme Improvements

CLI Output Theming (NEW!)

Major Enhancement: Complete visual overhaul of CLI output with branded Bengal identity.

All CLI commands now feature:

  • Bengal Orange (#FF9D00) as primary brand color
  • Semantic styling system (success, warning, error, header, path, etc.)
  • Enhanced header rendering with Panel components
  • Mouse emoji (ᘛ⁐̤ᕐᐷ) for errors - Bengal catches them!
  • Cross-platform color consistency with hex precision

Coverage: 29 unit tests + 14 integration tests covering all CLI commands.

Impact: Professional, consistent CLI experience that matches Bengal's branding and improves readability.

Appearance Control Update

Removed the legacy light/dark toggle button in favor of a unified dropdown control.

  • Dropdown manages Mode (System/Light/Dark) and Brand/Palette
  • Cleaner UI with single control point
  • theme-toggle.jsstill supports old.theme-togglebuttons for backward compatibility

List-Table Directive

Added MyST-compatiblelist-tabledirective for autodoc templates.

  • Fixes pipe character issues in type annotations (e.g.,str | None)
  • Renders parameters and attributes as proper HTML tables
  • Supports inline markdown (backticks render as<code>)

🏗️ Code Quality

Dependency Injection

BuildContext: Introduced proper dependency injection to eliminate temporary state mutation.

  • Newbengal.utils.build_context.BuildContext
  • Threaded through render/postprocess phases
  • Removes need forsite.pages/site.assetsswapping

ProgressReporter: Added reporter protocol with Rich adapter.

  • Routes all orchestration/render logging through reporter
  • Enables testing without console output
  • Cleaner separation of concerns

TemplateValidationService: Added validation service layer.

  • CLI--validatenow uses service interface
  • Decouples CLI from direct engine/validator access

Refactoring

Theme Resolution: Extracted theme chain and template directory resolution intobengal.utils.theme_resolution.

Build Orchestration: Pass explicit page/asset lists across phases instead of mutating Site fields.

Rendering Pipeline: Accept optional BuildContext with DI for parser/engine/enhancer.

Code Cleanup

Removed dead code throughout the codebase:

  • Unused exception variables
  • Deprecated classes (ResponseBuffer)
  • WIP stubs (TablePlugin)
  • Verified false positives from static analysis

Module Splitting

CLI Graph Commands: Split 1,050-line file into 5 focused modules (~200 lines each).

Files now incli/commands/graph/:

  • analyze.py
  • pagerank.py
  • communities.py
  • bridges.py
  • suggest.py

Markdown Parsers: Split 826-line file into 4 focused modules inrendering/parsers/.

⚠️ BREAKING: Import path changed frombengal.rendering.parsertobengal.rendering.parsers

Pygments Patch: Refactored monkey patch into clean, testable implementation.

  • Extracted to dedicatedPygmentsPatchclass
  • Added comprehensive test suite (22 tests)
  • Retains 3x speedup on code highlighting
  • Better maintainability

📊 Testing

All fixes include comprehensive test coverage:

  • PageProxy compatibility tests
  • Postprocess reporter error handling
  • Streaming quiet behavior
  • Pygments patch tests (22 tests)

Upgrading

pip install --upgrade bengal

Breaking Changes

⚠️ Parser Import Path Changed

If you imported parsers directly (advanced usage), update your imports:

1
2
3
4
5
# Old (0.1.2 and earlier)
from bengal.rendering.parser import MistuneParser

# New (0.1.3+)
from bengal.rendering.parsers import MistuneParser

Note: Most users won't be affected - this only impacts direct imports of parser classes.