Create a Theme

Bengal's theme system supports inheritance, so you can build on the default theme and override only what you need. This guide walks through creating, customizing, and testing a theme.

Scaffold a Theme

# Create a site-local theme (lives in your project)
bengal theme new my-theme

# Create an installable package (publishable to PyPI)
bengal theme new my-theme --mode package

# Extend a specific parent theme
bengal theme new my-theme --extends default

Site mode creates this structure:

themes/my-theme/
├── theme.toml              # Name and inheritance
├── templates/
│   ├── page.html           # Extends parent page.html
│   └── partials/
│       └── example.html
├── assets/
│   └── css/
│       └── style.css       # Your styles (directive base CSS is automatic)
└── dev/
    └── components/
        └── example.yaml    # Component variants for dev preview

Configure Your Site

Point your site config at the new theme:

# bengal.toml
[site]
theme = "my-theme"

Bengal resolves templates in priority order: your theme first, then its parent (via extends), then the default theme. You only need to override the templates you want to change.

Override Templates

Copy a template from the active theme to customize it:

# See what's available
bengal theme discover

# Copy a specific template
bengal theme swizzle partials/header.html

Swizzled templates are tracked with checksums. When the parent theme updates, bengal theme swizzle-updaterefreshes unchanged templates while preserving your modifications.

Template Inheritance

Your templates can extend parent templates:

{# templates/page.html #}
{% extends "page.html" %}

{% block content %}
<article class="my-theme-content">
  {{ content | safe }}
</article>
{% endblock %}

Bengal resolves the extends to the parent theme's page.htmlautomatically.

Add Styles

Yourassets/css/style.cssis loaded after the parent theme's CSS, so your styles override naturally via the cascade.

Bengal automatically includes base CSS for all directives (tabs, dropdowns, admonitions, steps, cards, code blocks). Your theme only needs to provide aesthetic styles — functional show/hide, accessibility, and prose contamination fixes are handled.

/* assets/css/style.css */

/* Override the primary color */
:root {
  --color-primary: #2563eb;
  --color-primary-light: #3b82f6;
}

/* Custom typography */
body {
  font-family: "Inter", system-ui, sans-serif;
  line-height: 1.7;
}

/* Style code blocks */
pre code {
  border-radius: 0.5rem;
  font-size: 0.875rem;
}

Test Your Theme

# Start dev server with live reload
bengal serve

# Validate theme structure
bengal theme validate themes/my-theme

# Debug template resolution
bengal theme debug
bengal theme debug --template page.html

The dev server watches your theme directory and rebuilds on changes.

Theme Configuration

Yourtheme.tomldeclares metadata and feature flags:

name = "my-theme"
extends = "default"

For richer configuration (feature flags, appearance, icons), use theme.yaml:

name: my-theme
version: "1.0.0"
parent: default

features:
  navigation:
    breadcrumbs: true
    toc: true
  content:
    code.copy: true
    lightbox: true
  search:
    suggest: true

appearance:
  default_mode: system
  default_palette: snow-lynx

Publish as a Package

If you scaffolded with--mode package, your theme is a pip-installable Python package:

cd bengal-theme-my-theme
pip install -e .    # Install locally for testing

The pyproject.tomlregisters your theme via entry points:

[project.entry-points.'bengal.themes']
my-theme = "bengal_themes.my_theme"

Once installed, any Bengal site can use it:

# bengal.toml
[site]
theme = "my-theme"

Publish to PyPI with uv publish or python -m build && twine upload dist/*.

Useful Commands