Themer Quickstart

Learn to customize Bengal themes and create your own designs.

Prerequisites

Understand Theme Resolution

Bengal looks for templates in this order:

1. Your project —templates/(overrides everything)
2. Your theme —themes/your-theme/templates/
3. Installed themes — Via pip/uv
4. Default theme — Built into Bengal

You only need to override what you want to change.

Create a Custom Theme

bengal new theme my-theme

This creates:

themes/my-theme/
├── theme.yaml
├── templates/
│   ├── base.html
│   ├── page.html
│   └── partials/
│       ├── header.html
│       └── footer.html
└── static/
    ├── css/
    │   └── style.css
    └── js/
        └── main.js

Configure Your Theme

Editconfig/_default/theme.yaml:

1
2

theme:
  name: "my-theme"

Override Templates Selectively

You don't need to copy all templates. Extend the default:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{# themes/my-theme/templates/base.html #}
{# Extend the base template if you want to reuse structure #}
{% extends "base.html" %}

{% block header %}
<header class="custom-header">
    <h1>{{ site.title }}</h1>
    {% for item in menu.main %}
    <a href="{{ item.url }}">{{ item.name }}</a>
    {% endfor %}
</header>
{% endblock %}

Everything not overridden inherits from the default theme (or parent theme).

Add Custom CSS

Createthemes/my-theme/static/css/custom.css:

1
2
3
4
5
6
7
8
9

:root {
    --color-primary: #3498db;
    --color-text: #2c3e50;
}

.custom-header {
    background: var(--color-primary);
    padding: 2rem;
}

Include in your template:

1
2
3

{% block extra_head %}
<link rel="stylesheet" href="{{ asset_url('css/custom.css') }}">
{% endblock %}

Template Variables

Key variables available in templates:

Debug Theme Issues

1
2
3
4
5
6
7
8

# Check theme resolution
bengal utils theme debug

# List available themes
bengal utils theme list

# Get theme info
bengal utils theme info default

Next Steps

• Theme Customization — Deep dive into overrides
• Template Functions — Available filters
• Variables Reference — All template variables
• Assets — CSS, JS, and image handling