---
title: Bengal 0.1.2
description: Critical bug fixes, cache improvements, and navigation enhancements
type: changelog
date: 2025-10-13
draft: false
lang: en
tags: [release, changelog, bug fixes]
keywords: [release, 0.1.2, bug fixes, cache, navigation]
category: changelog
---

# Bengal 0.1.2 - Critical Fixes & 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 by `bengal 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 survives `bengal site clean` operations
- You can cache the `.bengal/` directory in CI/CD for faster builds
- Incremental builds work reliably after cleaning output

### Clean Command Improvements

The `bengal site clean` command now has three modes:

```bash
# 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:** The `bengal new page` command now creates clean filenames.

**Before:**
```bash
bengal new page "My Tutorial"
# Created: "My Tutorial.md" (spaces in filename!)
```

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

The `next_in_section` and `prev_in_section` now:
- Respect `weight` metadata 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`, `autodoc/python`, `autodoc/cli`, `changelog`
- **Global**: `blog`, `page`, and others

Add `weight` to your documentation pages for explicit ordering:

```yaml
---
title: Step 1
---
```

```yaml
---
title: Step 2
---
```

### Documentation Template

**Fixed:** The `bengal new site` docs template now uses correct file structure and frontmatter.

- Section indexes use `_index.md` (not `index.md`)
- Modern frontmatter (`weight:` instead of deprecated `order:`)
- 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 missing `weight` metadata (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:
```bash
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

```bash
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:
```bash
# Clean and rebuild to fix URLs
bengal site clean
bengal site build
```

If you have docs with navigation issues:
```bash
# 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)

## 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 reported issues and provided feedback! Your bug reports made this release possible.
