---
title: Bengal 0.1.4
description: Configuration system overhaul, asset pipeline improvements, HTML formatting, link checking, and major architecture enhancements
type: changelog
date: 2025-11-25
draft: false
lang: en
tags: [release, changelog, config, assets, cli, css, theme, architecture]
keywords: [release, 0.1.4, config, assets, cli, css, theme, html, link-checker, pagecore]
category: changelog
---

# 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:**

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

:::{dropdown} Detailed Configuration Guide
:icon: settings
:open: false

**New structure:**

```tree
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
```

**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:**

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

**CLI introspection:**

```bash
bengal 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:**

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

:::{dropdown} How Asset Manifest Works
:icon: file
:open: false

**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:**

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

**Per-page override:**

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

:::{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:

```bash
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:**

```yaml
# 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:

```bash
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 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:

```bash
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:

:::{dropdown} CSS Modernization Details
:icon: palette
:open: false

**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

:::{tab-set}
:::{tab-item} UV

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

:::

:::{tab-item} pip

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

:::
:::{/tab-set}

### After Upgrading

1. **Config system**: Single-file configs (`bengal.toml`, `bengal.yaml`) still work! Migrate to directory-based config when ready using `bengal config init`
2. **Asset manifest**: Your next build will generate `asset-manifest.json` automatically
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 in `bengal.toml` or `config/_default/build.yaml` if desired

:::{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](https://github.com/lbliii/bengal)
- [Issue Tracker](https://github.com/lbliii/bengal/issues)
- [Full Changelog](https://github.com/lbliii/bengal/blob/main/changelog.md)

---

## Thank You

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