Build Profiles

Configure Bengal for different workflows with built-in profiles

4 min read 854 words

Bengal includes three built-in profiles optimized for different workflows:

Profile For Focus
writer Content authors Fast, clean builds
theme-dev Theme builders Template debugging
dev Framework contributors Full observability

Quick Start

# Content writing (default)
bengal build

# Theme development
bengal build --theme-dev

# Full debugging
bengal build --dev

Profile Comparison

Writer Profile (Default)

Best for: Content authors who want fast, clean builds without technical noise.

bengal build
# or explicitly:
bengal build --profile writer

Features:

  • ✅ Fast builds with minimal output
  • ✅ Content-focused health checks (links, directives)
  • ✅ Live progress display
  • ❌ No phase timing
  • ❌ No memory tracking
  • ❌ No debug output

Health Checks Enabled:

  • config— Configuration validation
  • output— Output file checks
  • links— Link validation
  • directives— MyST directive syntax

Theme Developer Profile

Best for: Theme builders who need template debugging and rendering insights.

bengal build --theme-dev
# or:
bengal build --profile theme-dev

Features:

  • ✅ Phase timing displayed
  • ✅ Template-focused health checks
  • ✅ Live progress with recent items (3 shown)
  • ✅ Build metrics collected
  • ✅ Verbose build stats
  • ❌ No memory tracking

Health Checks Enabled:

  • config,output,links,directives
  • rendering— Template rendering errors
  • navigation— Navigation structure
  • menu— Menu validation

Disabled:performance,cache,taxonomy(use--devfor these)

Developer Profile

Best for: Framework contributors who need full observability.

bengal build --dev
# or:
bengal build --profile dev
# or:
bengal build --debug

Features:

  • ✅ Phase timing displayed
  • ✅ Memory tracking enabled
  • ✅ Debug output enabled
  • ✅ All metrics collected
  • ✅ All health checks enabled
  • ✅ Recent items shown (5)

Health Checks Enabled:

  • All validators across all tiers (build, full, ci)

Profile Settings Comparison

Setting Writer Theme-Dev Developer
Phase timing ❌ ✅ ✅
Memory tracking ❌ ❌ ✅
Debug output ❌ ❌ ✅
Metrics collection ❌ ✅ ✅
Verbose build stats ❌ ✅ ✅
Live progress ✅ ✅ ✅
Recent items shown 0 3 5

Command Reference

Profile Flags

# Explicit profile selection
bengal build --profile writer
bengal build --profile theme-dev
bengal build --profile dev

# Shorthand flags
bengal build --theme-dev    # Same as --profile theme-dev
bengal build --dev          # Same as --profile dev
bengal build --debug        # Maps to --profile dev

Profile Precedence

When multiple flags are provided, precedence (highest to lowest):

  1. --devflag
  2. --theme-devflag
  3. --profileoption
  4. --debugflag
  5. Default (writer)

Profile + Other Options

Profiles can be combined with other build options:

# Theme development with verbose output
bengal build --theme-dev --verbose

# Developer mode with incremental builds
bengal build --dev --incremental

# Theme dev with template profiling
bengal build --theme-dev --profile-templates

# Fast mode overrides profile settings
bengal build --fast

Verbose vs Profile

--verboseand profiles are independent:

Flag What It Does
--verbose Controls output verbosity (show/hide details)
--quiet Minimal output (errors and summary only)
--profile Controls feature enablement (metrics, health checks) 
# Writer profile with verbose output (shows stats)
bengal build --verbose

# Dev profile with quiet output (hides stats)
bengal build --dev --quiet

Use Cases

Writing Content

# Fast, clean builds - default profile
bengal serve

The writer profile gives you:

  • Minimal terminal noise
  • Only content-related warnings
  • Fast feedback loop

Building a Theme

# Template-focused debugging
bengal serve --theme-dev

The theme-dev profile gives you:

  • Template rendering errors highlighted
  • Phase timing to identify slow templates
  • Component preview with live reload

Debugging a Problem

# Full observability
bengal build --dev --verbose

The dev profile gives you:

  • All health checks running
  • Memory tracking for leak detection
  • Full debug output
  • Metrics saved to.bengal/metrics/

Profile Metrics

When metrics collection is enabled (theme-dev and dev profiles):

.bengal/
└── metrics/
    ├── history.jsonl   # All builds (JSON Lines format)
    └── latest.json     # Most recent build

Metrics include:

  • Build duration per phase
  • Pages rendered
  • Assets processed
  • Template render times
  • Memory usage (dev profile only)

Quick Reference

# Profiles
bengal build                     # Writer (default)
bengal build --theme-dev         # Theme developer
bengal build --dev               # Full developer

# Profile + options
bengal build --dev --verbose     # Dev with verbose output
bengal build --theme-dev --fast  # Theme dev with fast mode

# Override config
bengal build --profile writer    # Force writer profile

Seealso