Bengal 0.1.4

Executive Summary

This release introduces a major configuration system overhaul with Hugo-style directory-based configs, improves asset pipeline reliability with deterministic manifests, adds HTML formatting and link checking, and includes significant architecture improvements for better performance and maintainability.

Key Highlights:

• 🎯 Directory-based configuration with environment awareness and build profiles
• 📦 Deterministic asset manifest eliminates stale fingerprints
• 📄 HTML output formatting (raw/pretty/minify modes)
• 🔗 Async link checker for site validation
• 🏗️ PageCore refactoring for better cache-proxy contracts
• 🎨 CSS modernization complete (phases 1-4)

Who should upgrade: All users. This is a backward-compatible patch release with no breaking changes.

🎯 Major Features

Configuration System Overhaul

Bengal now supports Hugo-style directory-based configuration with environment awareness and build profiles. Single-file configs (bengal.toml,bengal.yaml) still work—migrate when ready!

Quick start:

1
2
3

bengal config init              # Initialize config directory
bengal build --environment production  # Use environment-specific config
bengal build --profile writer   # Fast builds, quiet output

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

config/
├── _default/           # Base configuration (6 files)
│   ├── site.yaml      # Site metadata
│   ├── build.yaml     # Build settings
│   ├── content.yaml   # Content processing
│   ├── theme.yaml     # Appearance
│   ├── features.yaml  # Feature toggles
│   └── params.yaml    # User parameters
├── environments/       # Environment-specific overrides
│   ├── local.yaml
│   ├── preview.yaml
│   └── production.yaml
└── profiles/           # Persona-based configs
    ├── writer.yaml    # Fast builds
    ├── theme-dev.yaml # Template debugging
    └── dev.yaml       # Full observability

1
2
3
4
5

# In features.yaml - simple flags expand to full config
features:
  rss: true
  search: true
  json: true

1
2
3
4

bengal config show          # Show merged configuration
bengal config doctor        # Diagnose config issues
bengal config diff          # Compare configs
bengal config init          # Initialize config directory

Asset Pipeline Improvements

Deterministic asset manifest eliminates stale fingerprinted assets and keeps dev/production CSS in sync.

New CLI command:

1
2

bengal assets status        # Inspect asset mappings
bengal site build --clean-output  # Clean builds for CI/CD

HTML Output Formatting

Safe HTML formatter with three output modes: raw (fastest), pretty (formatted), and minify (smallest).

Configuration:

1
2
3

# In config/_default/build.yaml or bengal.toml
[html_output]
format = "pretty"  # or "raw" or "minify"

Per-page override:

1
2
3
4

---
title: My Page
no_format: true  # Skip formatting for this page
---

Link Checking

New async link checker for validating site links:

bengal health linkcheck

Features:

• Async HTTP client for fast checking
• Auto-builds site and purges cache before checking (eliminates false positives)
• Comprehensive validation with detailed error reporting
• Integrates with existingbengal healthcommand

Use cases: Pre-deployment validation, CI/CD pipeline checks, regular site maintenance.

🏗️ Architecture Improvements

PageCore Refactoring

Major refactoring to improve cache-proxy contract enforcement:

• PageCore dataclass: New composition pattern for cacheable page metadata
• PageProxy wrapping: PageProxy now wraps PageCore directly, simplifying the architecture
• Cache operations: Simplified serialization usingasdict(page.core)instead of manual field mapping
• Type safety: Better type hints and validation throughout

Impact: Cleaner code, better performance, easier to maintain.

Stable Section References

Path-based section references for reliable incremental builds:

• Path-based registry: O(1) dict-based lookup for sections using paths instead of object identity
• Feature flag:stable_section_referencesenables path-based tracking
• Dev server: Force full rebuild on file create/delete/move to preserve relationships
• Performance: Regression tests validate no performance degradation

Impact: More reliable incremental builds, especially when sections are renamed or moved.

Cacheable Protocol

Refactored cache entries to implement theCacheableprotocol:

• Type safety: GenericCacheStorehelper for type-safe cache operations
• Versioning: Built-in version checking for cache invalidation
• Consistency: All cache entries follow the same contract

📚 Autodoc Enhancements

URL Grouping

Automatic URL grouping for cleaner autodoc structure:

Modes:

• off: No grouping (default, backward compatible)
• auto: Auto-detect common prefixes (e.g.,bengal.→ strip from URLs)
• explicit: Manual prefix mapping

Example:

1
2
3
4
5
6

# In config/_default/autodoc.yaml
autodoc:
  python:
    grouping:
      mode: "auto"  # Auto-detect from __init__.py hierarchy
      strip_prefix: "bengal."

Before:/api/bengal/autodoc/extractors/python/
After:/api/extractors/python/

Alias & Inherited Members

• Alias detection: Automatically detects simple assignment aliases (e.g.,public_api = original_function) and documents them with provenance tracking
• Inherited members: Synthesizes inherited class members from base classes with configurable display (per-type control viainclude_inherited_by_type)
• Alias strategies: Configurable rendering (canonical,duplicate,list-only) for how aliases appear in documentation
• Better navigation: Improved autodoc navigation and template fixes

🖥️ CLI Enhancements

Command Metadata System

All CLI commands now have structured metadata for better discovery and documentation:

• Progress feedback: Long-running operations show progress indicators
• Unified helpers: Consistent error handling, site loading, and traceback configuration
• Better help: Improved help text organization and command discovery

Theme Debug CLI

New command to debug theme issues:

1
2

bengal theme debug
bengal theme debug --template page.html  # Show resolution for specific template

Features:

• Shows active theme chain (inheritance order)
• Displays template resolution paths (priority order)
• Validates theme chain (circular inheritance, missing themes)
• Shows template source locations for common templates

Standardized Output

All CLI commands now use a consistentCLIOutputsystem:

• Consistent styling and formatting
• Better error messages
• Progress indicators for long operations
• Unified command structure

Traceback Configuration

New--tracebackflag for configurable error display:

bengal build --traceback  # Show full tracebacks for debugging

🎨 CSS Modernization Complete

Bengal's default theme now uses cutting-edge CSS features across all four phases:

Impact: Modern, maintainable CSS that's easier to customize and performs better.

Typography Consolidation

Simplified typography system:

• Single.prosesystem: All prose content uses one consistent system
• Removed.has-prose-content: No longer needed with consolidated system
• Simplified page-header: Cleaner component structure

All content now uses the same typography foundation, making customization easier.

🌊 Mermaid Diagram Enhancements

Improved Toolbar

• Pan & Zoom: Navigate large diagrams
• Reliable initialization: Diagrams load consistently
• Copy action fix: Preserves mermaid syntax when copying

Mermaid diagrams are now more reliable and easier to interact with.

🧭 Navigation Improvements

Action Bar Breadcrumbs

New breadcrumb component adopted across documentation:

• Changelog pages: Consistent navigation trail
• CLI reference: Better context awareness
• API reference: Improved navigation

All documentation now has consistent, accessible breadcrumb navigation.

✨ Theme Polish

Fluid Text Effects

Enhanced mascot text with modern effects:

• Diagonal swirling motion: Dynamic animation
• Glow effect: Dark mode glow for better visibility
• Fluid text mask: Smooth appearance

The home page mascot now has a polished, modern look.

CSS Validation Fixes

Fixed@supportssyntax to use proper property-value pairs for W3C validation compliance.

📦 Rendering Improvements

Card Explanation Variant

New card variant optimized for explanations:

• Enhanced list styling
• Better table presentation
• Improved readability for documentation

Header Navigation Balance

Refined header navigation spacing:

• Balanced padding
• Reduced bottom padding to match top
• Better visual hierarchy

🔧 Dev Server Improvements

Live Reload Fixes

• Fixed spurious reloads: Dev server no longer triggers unnecessary rebuilds
• Proper live reload: HTML cache cleared after initial build for reliable live reload
• File events: Force full rebuild on create/delete/move to preserve section relationships

🔧 Core Improvements

IndexEntry Cacheable Protocol

RefactoredIndexEntryto implement theCacheableprotocol for better type safety and consistency.

Code Quality

• Cleanup of temporary files and test artifacts
• Simplified taxonomy eligibility checks
• Better code organization

📚 Documentation Updates

• Updated template README to reflect.prose-onlytypography system
• Added spacing optimization documentation
• CSS modernization progress tracking

Upgrading

uv pip install --upgrade bengal

pip install --upgrade bengal

After Upgrading

1. Config system: Single-file configs (bengal.toml,bengal.yaml) still work! Migrate to directory-based config when ready usingbengal config init
2. Asset manifest: Your next build will generateasset-manifest.jsonautomatically
3. CSS updates: Theme CSS is now fully modernized - no action needed
4. CLI improvements: New commands (bengal config,bengal health linkcheck,bengal assets status) available immediately
5. HTML formatting: Configure inbengal.tomlorconfig/_default/build.yamlif desired

What's Next

• Continued performance optimizations
• More CLI enhancements
• More theme components
• Enhanced documentation

Links

• Documentation
• Issue Tracker
• Full Changelog

Thank You

Thank you to everyone who contributed feedback, reported issues, and helped improve Bengal! Your contributions make each release better.