ᓚᘏᗢ Bengal

The documentation generator built on Python's free-threading future

Every layer — markdown parsing, syntax highlighting, templates, dev server — is pure Python, scales with your cores, and ships zero npm dependencies.

pip install bengal
bengal new site mysite && cd mysite && bengal serve

Why Bengal?

Bengal is a static site generator where the entire stack is Python you can read, debug, and extend. No JavaScript toolchains. No compiled C extensions in the critical path. Every library in the pipeline — Patitas (markdown), Rosettes (syntax highlighting), Kida (templates), Pounce (dev server) — is purpose-built for Python 3.14+ free-threading.

What this gets you:

• Scales with cores — Parallel builds with true thread parallelism on Python 3.14t. No GIL contention.
• AI-native output — Generates llms.txt, agent manifests, per-page JSON, and Content Signals so AI agents can discover, navigate, and respect your content policies.
• Sub-second rebuilds — Provenance-based incremental builds with content-addressed hashing. Only changed pages rebuild.
• Python-native workflows — Jupyter .ipynb rendering, autodoc for Python/CLI/OpenAPI, pip install and go.
• Batteries included — Sitemap, RSS, social cards, search indexes, broken link detection, content validation.
• Extensible — Pluggable engines for templates, Markdown, and syntax highlighting. 9 plugin extension points.

Use Bengal For

• 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

Quick Commands

Aliases: b (build), s (serve), v (validate)

Site Scaffolding

bengal new site

🎯 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

bengal new site my-docs --template docs
bengal new site my-blog --template blog
bengal new site portfolio --template portfolio

# 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-run

# 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 --force

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.

Features

📚 Full documentation: lbliii.github.io/bengal

Configuration

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

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 →

Project Structure

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

Theming

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 %}

Pluggable Engines

Bengal follows a "bring your own" pattern — swap engines without changing your content.

# config/_default/content.yaml
markdown:
  parser: patitas  # default, or mistune (legacy), python-markdown

# config/_default/theme.yaml
highlighting:
  backend: rosettes

Requirements

• Python 3.14+ (uses free-threading and PEP 784 compression)
• Linux, macOS, Windows

Philosophy

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.

Documentation

📚 lbliii.github.io/bengal

Development

git clone https://github.com/lbliii/bengal.git
cd bengal
uv sync --group dev
pytest

Multi-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.

The Bengal Ecosystem

A structured reactive stack — every layer written in pure Python for 3.14t free-threading.

Python-native. Free-threading ready. No npm required.

License

MIT