Themer Quickstart

Customize themes and create your own designs

3 min read 563 words
Edit this page

Was this page helpful?

Customize Bengal themes and create your own designs in 30 minutes.

Note

Do I need this? Yes if you want to change layouts, CSS, or template structure. Skip if you only write Markdown — the default theme works without theming.

Prerequisites

0/4 complete
  • Bengal installed
  • Basic knowledge of HTML
  • Familiarity with CSS
  • Basic template syntax (Bengal uses Kida, similar to Jinja2 but with{% end %}closers)

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 or uv
  4. Default theme — Built into Bengal

You only need to override what you want to change.

  1. 1

    Create a custom theme

    BASH
    bengal theme new --slug my-theme

    This creates:

    TREE-SITTER-QUERY
    themes/my-theme/
├── theme.toml
├── README.md
├── templates/
│   ├── base.html
│   ├── home.html
│   ├── page.html
│   └── partials/
└── assets/
    └── css/
        └── style.css
  2. 2

    Configure your theme

    Updatebengal.toml:

    TOML
    [build]
theme = "my-theme"

    Or use config/_default/build.yamlfor split configuration:

    YAML
    build:
  theme: "my-theme"
  3. 3

    Override templates selectively

    You do not need to copy all templates. Extend the default:

    HTML
    {# themes/my-theme/templates/base.html #}
{% extends "base.html" %}

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

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

  4. 4

    Add custom CSS

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

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

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

    Include in your template:

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

Template Variables

Key variables available in templates (all support safe dot-notation access):

Variable Description
site.title Site title from configuration
site.description Site description
site.baseurl Site base URL
site.pages All pages in the site
menus.main Main navigation menu (safe access)
page.title Current page title
page.content Rendered HTML content (use with| safe)
page.href Page URL with baseurl applied
page.date Publication date
page.tags List of tags
page.description Page description
params Page frontmatter (cascades page → section → site)
theme Theme configuration (safe dot-notation access)
bengal Engine metadata

Bengal provides 80+ template functions. Common ones:

  • asset_url('path')— Generate asset URLs
  • url_for('path')— Generate page URLs
  • get_menu('name')— Get a navigation menu
  • time_ago / date_iso — Format dates ({{ page.date | time_ago }})
  • truncate_chars(text, length)— Truncate text

Debug Theme Issues

BASH
# List available themes
bengal theme list

# Get theme info
bengal theme info --slug default

# Debug theme resolution
bengal theme debug

# Discover installed themes
bengal theme discover

# Swizzle a template for customization
bengal theme swizzle --template-path partials/header.html

Next Steps