---
title: Bengal 0.1.3
description: Performance, stability, theme enhancements, and critical bug fixes
type: changelog
date: 2025-10-20
draft: false
lang: en
tags: [release, changelog, performance, bug fixes]
keywords: [release, 0.1.3, performance, stability, bug fixes]
category: changelog
---

# Bengal 0.1.3 - Performance, Stability & 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.

```bash
# 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 with `PYTHON_GIL=0` to 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_pages` and `Site.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.

### Parallel Related Posts

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's `max_workers` configuration
- 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 missing `permalink` property → broken navigation links
2. PageProxy missing `_site` reference → couldn't resolve baseurl
3. PageProxy missing `output_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 for `rendered_html` to support rendering phase

### Autodoc CLI Template Selection

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

Changed autodoc to set `type: autodoc/cli` instead of `type: 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'` (and `next_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 when `preprocess: 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.js` still supports old `.theme-toggle` buttons for backward compatibility

### List-Table Directive

Added MyST-compatible `list-table` directive 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.

- New `bengal.utils.build_context.BuildContext`
- Threaded through render/postprocess phases
- Removes need for `site.pages`/`site.assets` swapping

**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 `--validate` now uses service interface
- Decouples CLI from direct engine/validator access

### Refactoring

**Theme Resolution**: Extracted theme chain and template directory resolution into `bengal.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 in `cli/commands/graph/`:
- `analyze.py`
- `pagerank.py`
- `communities.py`
- `bridges.py`
- `suggest.py`

**Markdown Parsers**: Split 826-line file into 4 focused modules in `rendering/parsers/`.

⚠️ **BREAKING**: Import path changed from `bengal.rendering.parser` to `bengal.parsing`

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

- Extracted to dedicated `PygmentsPatch` class
- 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

```bash
pip install --upgrade bengal
```

### Breaking Changes

⚠️ **Parser Import Path Changed**

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

```python
# Old (0.1.2 and earlier)
from bengal.rendering.parser import MistuneParser

# New (0.1.3+)
from bengal.parsing import MistuneParser
```

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


## Links

- [Documentation](https://github.com/lbliii/bengal)
- [Issue Tracker](https://github.com/lbliii/bengal/issues)
- [Full Changelog](https://github.com/lbliii/bengal/blob/main/changelog.md)
