ᓚᘏᗢ Bengal

A Python static site generator for documentation, blogs, and product sites

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

---

What is Bengal?

Bengal 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, Content Signals
• Fast builds — Parallel builds, incremental rebuilds, Zstandard-compressed caching
• Modern Python — Python 3.14+ with free-threading support, fully typed
• Content workflows — Native Jupyter .ipynb rendering, Binder/Colab links
• Batteries included — Auto-generated API docs, content validation, site analysis
• Extensible — Pluggable engines for templates, Markdown, and syntax highlighting

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

| 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)

---

Site Scaffolding

<details> <summary><strong>Interactive Wizard</strong> — Guided setup with presets</summary>

Run without arguments for a guided experience:

bengal new site

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

</details> <details> <summary><strong>Direct Template Selection</strong> — Skip prompts with explicit options</summary>

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 portfolio

Available 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 |

</details> <details> <summary><strong>Add Sections to Existing Sites</strong> — Expand without recreating</summary>

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

Section 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 |

</details> <details> <summary><strong>Custom Skeleton Manifests</strong> — YAML-defined site structures</summary>

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

Example 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 path
• type — Component identity (blog, doc, landing)
• variant — Visual style variant
• props — Frontmatter data (title, weight, etc.)
• content — Markdown body content
• pages — Child components (makes this a section)
• cascade — Values inherited by all descendants

</details>

---

Features

| Feature | Description | Docs | |---------|-------------|------| | SEO & Discovery | Sitemap, RSS, canonical URLs, Open Graph, social cards, search, JSON/LLM output, llms.txt, Content Signals | 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

---

Configuration

<details> <summary><strong>Single-file</strong> — Simple projects</summary>

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

</details> <details> <summary><strong>Directory-based</strong> — Multi-environment projects</summary>

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

</details>

📖 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 sear