A Python static site generator for documentation, blogs, and product sites
pip install bengal
bengal new site mysite && cd mysite && bengal serveBengal is a Python static site generator for documentation sites, blogs, knowledge bases, and product sites. It focuses on fast builds, strong defaults, and discovery-friendly output: sitemaps, feeds, canonical URLs, Open Graph tags, social cards, search indexes, and JSON/LLM exports.
Why people pick it:
- Search-friendly output — Sitemap, RSS, canonical URLs, Open Graph tags, social cards
- Fast builds — Parallel builds, incremental rebuilds, Zstandard-compressed caching
- Modern Python — Python 3.14+ with free-threading support, fully typed
- Content workflows — Native Jupyter
.ipynbrendering, Binder/Colab links - Batteries included — Auto-generated API docs, content validation, site analysis
- Extensible — Pluggable engines for templates, Markdown, and syntax highlighting
- Documentation sites — Versioned docs, API reference, search, and internal linking
- Blogs and journals — Tags, categories, feeds, related content, and social sharing
- Knowledge bases — Markdown-first publishing with validation and JSON search indexes
- Product and marketing sites — Landing pages, content collections, and social cards
| Command | Description |
|---|---|
bengal build |
Production build |
bengal serve |
Dev server with live reload |
bengal validate |
Health checks and validation |
bengal fix |
Auto-fix common issues |
bengal graph report |
Site structure analysis |
Aliases: b (build), s (serve), v (validate)
Interactive Wizard — Guided setup with presets
Run without arguments for a guided experience:
bengal new siteThe wizard prompts for site name, base URL, and presents preset options:
🎯 What kind of site are you building?
📝 Blog - Personal or professional blog
📚 Documentation - Technical docs or guides
💼 Portfolio - Showcase your work
🛒 Product - Product site with listings and features
📄 Resume - Professional resume/CV site
📦 Blank - Empty site, no initial structure
⚙️ Custom - Define your own structure
Each preset creates a complete site with appropriate sections, sample content, and configuration.
Direct Template Selection — Skip prompts with explicit options
Create sites non-interactively with --template:
bengal new site my-docs --template docs
bengal new site my-blog --template blog
bengal new site portfolio --template portfolioAvailable templates:
| Template | Description | Sections Created |
|---|---|---|
default |
Basic site structure | Home page only |
blog |
Personal/professional blog | blog, about |
docs |
Technical documentation | getting-started, guides, reference |
portfolio |
Showcase work | about, projects, blog, contact |
product |
Product site with listings | products, features, pricing, contact |
resume |
Professional CV | Single resume page |
landing |
Single-page landing | Home, privacy, terms |
changelog |
Release notes timeline | Changelog with versions |
Add Sections to Existing Sites — Expand without recreating
Add new content sections to an existing Bengal site:
# Add multiple sections
bengal init --sections docs --sections tutorials
# Add sections with sample content
bengal init --sections blog --with-content --pages-per-section 5
# Preview without creating files
bengal init --sections api --dry-runSection type inference:
| Name Pattern | Inferred Type | Behavior |
|---|---|---|
| blog, posts, articles, news | blog |
Date-sorted, post-style |
| docs, documentation, guides, tutorials | doc |
Weight-sorted, doc-style |
| projects, portfolio | section |
Standard section |
| about, contact | section |
Standard section |
Custom Skeleton Manifests — YAML-defined site structures
For complex or repeatable scaffolding, define structures in YAML manifests:
# Preview what would be created
bengal project skeleton apply my-structure.yaml --dry-run
# Apply the skeleton
bengal project skeleton apply my-structure.yaml
# Overwrite existing files
bengal project skeleton apply my-structure.yaml --forceExample manifest (docs-skeleton.yaml):
name: Documentation Site
description: Technical docs with navigation sections
version: "1.0"
cascade:
type: doc # Applied to all pages
structure:
- path: _index.md
props:
title: Documentation
description: Project documentation
weight: 100
content: |
# Documentation
Welcome! Start with our [Quick Start](getting-started/quickstart/).
- path: getting-started/_index.md
props:
title: Getting Started
weight: 10
cascade:
type: doc
pages:
- path: installation.md
props:
title: Installation
weight: 20
content: |
# Installation
```bash
pip install your-package
```
- path: quickstart.md
props:
title: Quick Start
weight: 30
content: |
# Quick Start
Your first project in 5 minutes.
- path: api/_index.md
props:
title: API Reference
weight: 30
content: |
# API Reference
Complete API documentation.Component Model:
path— File or directory pathtype— Component identity (blog, doc, landing)variant— Visual style variantprops— Frontmatter data (title, weight, etc.)content— Markdown body contentpages— Child components (makes this a section)cascade— Values inherited by all descendants
| Feature | Description | Docs |
|---|---|---|
| SEO & Discovery | Sitemap, RSS, canonical URLs, Open Graph tags, social cards, search, JSON/LLM output | SEO & Discovery → |
| Directives | Tabs, admonitions, cards, dropdowns, code blocks | Content → |
| Notebooks | Native Jupyter .ipynb rendering, Binder/Colab links |
Notebooks → |
| Autodoc | Generate API docs from Python, CLI, OpenAPI | Autodoc → |
| Remote Sources | Pull content from GitHub, Notion, REST APIs | Sources → |
| Image Processing | Resize, crop, format conversion (WebP/AVIF), srcset generation | Images → |
| Content Collections | Type-safe frontmatter with dataclass/Pydantic schemas | Collections → |
| Theming | Dark mode, responsive, syntax highlighting, search | Theming → |
| Validation | Health checks, broken link detection, auto-fix | Building → |
| Performance | Parallel builds, incremental rebuilds, streaming | Large Sites → |
| Zero-Config Deploy | Auto-detects GitHub Pages, Netlify, Vercel | Deployment → |
📚 Full documentation: lbliii.github.io/bengal
Single-file — Simple projects
# bengal.toml
[site]
title = "My Site"
baseurl = "https://example.com"Directory-based — Multi-environment projects
config/
├── _default/ # Base configuration
│ ├── site.yaml
│ └── build.yaml
├── environments/ # Environment overrides
│ └── production.yaml
└── profiles/ # Build profiles
└── dev.yaml
bengal build -e production # Production environment
bengal build --profile dev # Development profile📖 Configuration guide: Configuration →
mysite/
├── content/ # Markdown pages
├── templates/ # Custom templates (optional)
├── assets/ # Static files (CSS, JS, images)
├── data/ # YAML/JSON data files
├── config/ # Configuration directory
└── public/ # Build output
Bengal ships with a modern, accessible default theme:
- Dark mode with system preference detection
- Responsive design with mobile navigation
- Syntax highlighting with copy buttons
- Table of contents with scroll spy
- Full-text search (Lunr.js)
Customize templates:
{# templates/page.html #}
{% extends "base.html" %}
{% block content %}
<article class="prose">
<h1>{{ page.title }}</h1>
{{ content | safe }}
</article>
{% endblock %}Bengal follows a "bring your own" pattern — swap engines without changing your content.
Template Engines
| Engine | Description | Install |
|---|---|---|
| Kida (default) | Bengal's native engine. AST-native, free-threading safe, Jinja2-compatible syntax | Built-in |
| Jinja2 | Industry-standard with extensive ecosystem | Built-in |
# config/_default/site.yaml
template_engine: kida # or jinja2Markdown Parsers
| Parser | Description | Install |
|---|---|---|
| Patitas (default) | Bengal's native parser. Typed AST, O(n) parsing, thread-safe | Built-in |
| Mistune | Fast, modern parser | Built-in |
| Python-Markdown | Full-featured, extensive extensions | Built-in |
# config/_default/content.yaml
markdown:
parser: patitas # default, or mistune (legacy), python-markdownSyntax Highlighters
| Backend | Description | Install |
|---|---|---|
| Rosettes (default) | Lock-free, 55+ languages, O(n) guaranteed | pip install rosettes |
# config/_default/theme.yaml
highlighting:
backend: rosettesCustom backends can be registered via register_backend().
- Python 3.14+ (uses free-threading and PEP 784 compression)
- Linux, macOS, Windows
Bengal prioritizes correctness and clarity over backwards compatibility.
Each release represents the best solution we know how to deliver. When existing behavior no longer reflects the best design, it changes. Upgrades may require reading release notes and making adjustments.
- Fail loudly — Breaking changes produce clear errors
- User control — You choose when to upgrade; we choose what changes
- No hidden layers — No compatibility shims or deprecated code paths
If you need multi-year stability, pin your version.
git clone https://github.com/lbliii/bengal.git
cd bengal
uv sync --group dev
pytestMulti-repo workspace: With bengal, patitas, rosettes, etc. as siblings, copy workspace-root.example/pyproject.toml to the parent directory and run uv sync from there. The workspace root overrides sources so all packages use local versions. CI and end users (no workspace root) use PyPI.
A structured reactive stack — every layer written in pure Python for 3.14t free-threading.
| ᓚᘏᗢ | Bengal | Static site generator ← You are here | Docs |
| ∿∿ | Purr | Content runtime | — |
| ⌁⌁ | Chirp | Web framework | Docs |
| =^..^= | Pounce | ASGI server | Docs |
| )彡 | Kida | Template engine | Docs |
| ฅᨐฅ | Patitas | Markdown parser | Docs |
| ⌾⌾⌾ | Rosettes | Syntax highlighter | Docs |
Python-native. Free-threading ready. No npm required.
MIT