# Bengal 0.1.4 URL: /releases/0.1.4/ Section: releases Tags: release, changelog, config, assets, cli, css, theme, architecture Date: 2025-11-25 -------------------------------------------------------------------------------- Bengal 0.1.4 - Configuration Overhaul & Major Enhancements 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 3bengal config init # Initialize config directory bengal build --environment production # Use environment-specific config bengal build --profile writer # Fast builds, quiet output Settings Detailed Configuration Guide New structure: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16config/ β”œβ”€β”€ _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 Environment auto-detection: Netlify: Detects NETLIFY=true Vercel: Detects VERCEL=1 GitHub Actions: Detects GITHUB_ACTIONS=true Default: Falls back to local Smart feature toggles: 1 2 3 4 5# In features.yaml - simple flags expand to full config features: rss: true search: true json: true CLI introspection: 1 2 3 4bengal config show # Show merged configuration bengal config doctor # Diagnose config issues bengal config diff # Compare configs bengal config init # Initialize config directory Backward compatibility: Single-file configs (bengal.toml, bengal.yaml) still work! If config/ exists, it takes precedence. Asset Pipeline Improvements Deterministic asset manifest eliminates stale fingerprinted assets and keeps dev/production CSS in sync. New CLI command: 1 2bengal assets status # Inspect asset mappings bengal site build --clean-output # Clean builds for CI/CD File How Asset Manifest Works What this fixes: Eliminates stale fingerprinted assets (e.g., style.95230091.css) persisting after updates Ensures dev and production CSS stay in sync Provides reliable asset resolution without glob matching How it works: During build, Bengal writes public/asset-manifest.json with mappings like {"css/style.css": "css/style.a1b2c3.css"} asset_url() helper now consults the manifest first (with glob fallback for backward compatibility) Stale fingerprinted files are automatically cleaned up before writing new ones 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 --- Note Note The formatter preserves protected regions (code blocks, pre tags) and only formats safe HTML. 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 existing bengal health command 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 using asdict(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_references enables 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 the Cacheable protocol: Type safety: Generic CacheStore helper 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 via include_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 2bengal 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 consistent CLIOutput system: Consistent styling and formatting Better error messages Progress indicators for long operations Unified command structure Traceback Configuration New --traceback flag 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: Palette CSS Modernization Details Phase 1: Modern CSS features CSS nesting throughout Logical properties (margin-inline, padding-block, etc.) Container queries for navigation Enhanced :has() selector usage Phase 2: Logical Properties Expansion Converted all directional properties to logical equivalents Better RTL (right-to-left) language support Consistent spacing system Phase 3: Advanced Features Subgrid support View transitions Scroll animations Color functions (color-mix()) Phase 4: Polish & Performance GPU-accelerated animations (translate3d()) Smooth transitions with cubic-bezier App-quality interactions Performance optimizations Impact: Modern, maintainable CSS that's easier to customize and performs better. Typography Consolidation Simplified typography system: Single .prose system: 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 @supports syntax 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 Refactored IndexEntry to implement the Cacheable protocol 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-only typography system Added spacing optimization documentation CSS modernization progress tracking Upgrading UV pip uv pip install --upgrade bengal pip install --upgrade bengal After Upgrading Config system: Single-file configs (bengal.toml, bengal.yaml) still work! Migrate to directory-based config when ready using bengal config init Asset manifest: Your next build will generate asset-manifest.json automatically CSS updates: Theme CSS is now fully modernized - no action needed CLI improvements: New commands (bengal config, bengal health linkcheck, bengal assets status) available immediately HTML formatting: Configure in bengal.toml or config/_default/build.yaml if desired Note Note Breaking Changes: None! This is a patch release with backward-compatible improvements. All existing configurations continue to work. 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. -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1509 - Reading Time: 8 minutes