Bengal 0.1.2

Critical bug fixes, cache improvements, and navigation enhancements

Released: October 13, 2025

This release fixes several critical bugs that affected core functionality including build caches, URL generation, and navigation. It also includes major improvements to the test suite with property-based testing.

What You Need to Know

🔥 Build Cache Location Changed

IMPORTANT: The build cache location has moved and will be automatically migrated.

  • Old location:public/.bengal-cache.json(deleted bybengal site clean)
  • New location:.bengal/cache.json(survives clean operations)

What happens:

  1. On your first build with 0.1.2, the old cache is automatically copied to the new location
  2. The old cache file is left in place (you can delete it manually)
  3. Add.bengal/to your.gitignore

Why this matters:

  • Cache now survivesbengal site cleanoperations
  • You can cache the.bengal/directory in CI/CD for faster builds
  • Incremental builds work reliably after cleaning output

Clean Command Improvements

Thebengal site cleancommand now has three modes:

1
2
3
4
5
6
7
8
# Clean output only (preserves cache for fast rebuilds)
bengal site clean

# Clean output AND cache (for testing cold builds)
bengal site clean --cache

# Same as --cache
bengal site clean --all

This gives you control over whether you want to keep the cache for fast rebuilds or test a completely fresh build.

Major Bug Fixes

Page URL Generation

Fixed: Child pages in subdirectories now generate correct hierarchical URLs.

Before:

  • File:reference/getting-started.md
  • URL:/getting-started/❌ (wrong!)

After:

  • File:reference/getting-started.md
  • URL:/reference/getting-started/✅ (correct!)

This was a critical bug where pages lost their parent directory in the URL. The fix ensures all pages respect the folder structure.

Page Creation

Fixed: Thebengal new pagecommand now creates clean filenames.

Before:

1
2
bengal new page "My Tutorial"
# Created: "My Tutorial.md" (spaces in filename!)

After:

1
2
3
bengal new page "My Tutorial"
# Created: "my-tutorial.md" (clean, slugified)
# Title in file: "My Tutorial" (preserved for display)

URLs and filenames are now always clean, while the page title preserves your formatting.

Documentation Navigation

Fixed: Sequential navigation (next/previous links) now works correctly in documentation.

Thenext_in_sectionandprev_in_sectionnow:

  • Respectweightmetadata for ordering (lower numbers = earlier in sequence)
  • Skip index pages (_index.md,index.md)
  • Stay within section boundaries (no jumping between sections)

Navigation modes by content type:

  • Section-based:doc,tutorial,api-reference,cli-reference,changelog
  • Global:blog,page, and others

Addweightto your documentation pages for explicit ordering:

1
2
3
---
title: Step 1
---

1
2
3
---
title: Step 2
---

Documentation Template

Fixed: Thebengal new sitedocs template now uses correct file structure and frontmatter.

  • Section indexes use_index.md(notindex.md)
  • Modern frontmatter (weight:instead of deprecatedorder:)
  • Proper cascade declarations (cascade: type: doc)
  • Fixed internal links with proper trailing slashes

New documentation sites now work correctly out of the box.

Template Syntax

Fixed: Jinja2 syntax errors in blog templates that could cause rendering failures.

Enhancements

Better Logging

Added helpful debug logging:

  • Output path configuration details
  • Pages missingweightmetadata (gentle hints for better navigation)

The logging helps you understand what's happening during builds and guides you toward best practices.

New Health Checks

Two new validation checks help catch problems early:

  1. Weight-Based Navigation Validator

    • Verifies navigation respects weight ordering
    • Checks navigation stays within sections
    • Catches cross-section navigation bugs

  2. Output Path Completeness

    • Ensures all pages have output paths set
    • Prevents URL generation issues

Run health checks with:

bengal health

Test Suite Improvements

Massive improvements to test quality and coverage:

Property-Based Testing (NEW!)

  • 115 property tests generating 11,600+ examples per test run
  • 4 bugs discovered and fixed (including critical production issues)
  • Tests for URLs, paths, slugification, pagination, dates, and text utilities

Parametrized Tests

  • 6 test files refactored for better visibility
  • 25 opaque loop-based tests → 66 visible parametrized test cases
  • 80% faster debugging (instant identification of failing cases)

Test Performance

  • Parallel execution enabled (pytest-xdist)
  • 30-40% faster test runs with better fixture scoping
  • Timeout protection (300s) prevents hanging tests

New URL Test Coverage

  • 5 comprehensive test files (500+ new tests)
  • Covers URL generation, content types, templates, archives, and full integration
  • High confidence in URL and navigation correctness

Upgrading

pip install --upgrade bengal

After Upgrading

  1. Build cache migration: Your cache will be automatically migrated on first build
  2. Update .gitignore: Add.bengal/to your.gitignore
  3. No other changes needed: Your content and configuration will work as-is

If You Were Affected by Bugs

If you had child pages with wrong URLs:

1
2
3
# Clean and rebuild to fix URLs
bengal site clean
bengal site build

If you have docs with navigation issues:

1
2
3
# Add weight metadata to your pages
# Edit your .md files and add:
# weight: 10  (lower = earlier in sequence)

Dependencies

New dependency for property-based testing:

  • hypothesis>=6.92.0(dev dependency only)

Thank You

Thank you to everyone who reported issues and provided feedback! Your bug reports made this release possible.