Migration Express

Key Capabilities

Bengal is a static site generator that produces HTML, CSS, and JavaScript from Markdown content and Kida templates.

What Bengal Does

Content & Authoring

• MyST Markdown — Directives, admonitions, cross-references, tabs, cards
• 50+ Built-in Directives — Code tabs, dropdowns, galleries, video embeds, versioning badges
• Content Collections — Type-safe frontmatter validation with dataclass or Pydantic schemas
• Mixed Content Types — Docs, blog, landing pages, changelogs in one site

Performance

• Kida Templates — 1.81x faster than Jinja2 under concurrent workloads
• Incremental Builds — 35-80ms rebuilds for single-page edits
• Free-Threading — True parallelism on Python 3.14+ (no GIL contention)
• Parallel Rendering — 2-4x speedup on multi-core systems

Developer Experience

• Auto-generated API Docs — From Python source, CLI tools, and OpenAPI specs
• Image Processing — Resize, crop, format conversion (WebP/AVIF), srcset generation
• Zero-Config Deploy — Auto-detects GitHub Pages, Netlify, Vercel
• Theme System — Install themes from PyPI, swizzle templates, 1,100+ CSS tokens

Quality & Validation

• Health Checks — Broken links, missing images, frontmatter validation
• Auto-Fix —bengal fixrepairs common issues automatically
• Site Analysis — Graph visualization, orphan detection, content metrics

Technical Details

How Content is Organized

Your folder structure becomes your site structure. No configuration required.

The Three Content Types

content/
└── about.md  →  /about/

content/
└── blog/
    ├── _index.md     →  /blog/ (list page)
    ├── post-1.md     →  /blog/post-1/
    └── post-2.md     →  /blog/post-2/

content/
└── gallery/
    ├── index.md      →  /gallery/
    ├── photo-1.jpg   (co-located asset)
    └── photo-2.jpg   (co-located asset)

Quick Reference

docs/
├── _index.md
├── getting-started/
│   ├── _index.md
│   └── installation.md
└── advanced/
    ├── _index.md
    └── plugins.md

---
title: Docs
cascade:
  type: doc
  toc: true
---

Frontmatter Reference

Complete reference for all frontmatter fields available in Bengal pages.

Required Fields

Common Fields

Taxonomy Fields

Author Patterns

Bengal supports multiple author patterns for flexibility:

Simple string (reference to data registry):

author: lbliii

Nested object (inline):

author:
  name: Lawrence Lane
  github: lbliii
  bio: Technical writer and developer

Multiple authors (list of strings or objects):

authors:
  - lbliii
  - name: Jane Smith
    github: janesmith

Flat author fields (legacy pattern):

author: Lawrence Lane
author_avatar: /images/lawrence.jpg
author_title: Senior Developer
author_bio: Technical writer and developer
author_links:
  - text: GitHub
    url: https://github.com/lbliii

Author Data Registry

Define authors once indata/authors.yamland reference by key:

# data/authors.yaml
lbliii:
  name: Lawrence Lane
  github: lbliii
  bio: Technical writer and developer
  avatar: /images/lawrence.jpg

Then reference in frontmatter:

author: lbliii

Access in templates:

{% let author_info = site.data.authors[page.metadata.author] %}
{{ author_info.name }} — {{ author_info.bio }}

Component Model Fields

Bengal uses a Component Model where every page has three aspects: identity (type), appearance (variant), and data (props).

SEO Fields

Navigation Fields

Advanced Fields

Custom Fields (Props)

Any fields not part of Bengal's standard frontmatter are automatically available as custom props. Add them at the top level of your frontmatter.

Standard fields (extracted to PageCore):

• title, description, date, draft, weight, slug, url, aliases, lang
• tags, categories, keywords, authors, category
• type, variant, layout, template
• canonical, noindex, og_image, og_type
• menu, nav_title, parent
• cascade, outputs, resources, toc

Custom fields (Component Model props):

• Any field not listed above goes intopage.props
• Access in templates viapage.params (includes all frontmatter) or page.props(custom fields only)

Example

---
title: My Page
description: Page description
weight: 10
type: doc
icon: code
card_color: blue
custom_setting: value
---

Access custom fields in templates:

{# page.params includes all frontmatter (standard + custom) #}
{{ page.params.icon }}
{{ page.params.get('card_color', 'default') }}

{# page.props contains only custom fields #}
{{ page.props.icon }}

Note: The props: key is only used in skeleton manifests (bengal project skeleton apply). For regular markdown files, use flat frontmatter (all fields at top level).

Example

---
title: Getting Started with Bengal
description: Learn how to install and configure Bengal for your first site
date: 2025-01-15
draft: false
weight: 10
tags: [tutorial, beginner]
categories: [Getting Started]
authors: [jane-doe]
type: tutorial
variant: wide
cascade:
  type: doc
difficulty: beginner
time_estimate: 15 minutes
---

In this example:

• Standard fields (title, date, weight, etc.) are extracted to PageCore
• difficulty and time_estimate are custom props accessible via page.params
• cascade propagates type: docto all child pages

Cascade Configuration

Thecascadefield applies values to all descendant pages:

---
title: Documentation
cascade:
  type: doc
  variant: docs
  draft: false
---

All pages under this section inherit these values unless they override them. Page-level values always take precedence over cascaded values.

Configuration

Control Bengal's behavior throughbengal.tomland environment-specific settings.

Configuration Methods

Bengal loads configuration from either theconfig/ directory (preferred) OR bengal.toml (legacy/simple). If config/ exists, bengal.tomlis ignored.

Overrides apply in order: Base Config → Environment Overrides → CLI Flags.

Quick Start

# bengal.toml
[site]
title = "My Site"
baseurl = "https://example.com"
language = "en"

[build]
output_dir = "public"

[theme]
name = "default"

Configuration Patterns

# bengal.toml - everything in one place
[site]
title = "My Blog"

[build]
output_dir = "public"

[theme]
name = "default"

config/
├── _default/
│   ├── site.yaml
│   ├── build.yaml
│   └── theme.yaml
└── environments/
    ├── production.yaml
    └── staging.yaml

Environment Overrides

Run with different settings per environment:

bengal build --environment production

# config/environments/production.yaml
site:
  baseurl: "https://example.com"

build:
  minify_html: true
  strict_mode: true

assets:
  fingerprint: true

Build Options Reference

Key[build]configuration options:

Asset Options

Configure asset processing in the[assets]section:

[assets]
minify = true
optimize = true
fingerprint = true

Template Validation

Enablevalidate_templatesto catch template syntax errors early during builds:

[build]
validate_templates = true

When enabled, Bengal validates all templates (HTML/XML) in your template directories before rendering. This provides early feedback on syntax errors, even for templates that might not be used by every page.

[build]
validate_templates = true

[build]
validate_templates = true
strict_mode = true

When to enable:

• During active theme development
• In CI/CD pipelines
• When debugging template issues

What it catches:

• Template syntax errors (unclosed tags, invalid filters) in Kida and Jinja2
• Unknown filter names
• Template assertion errors