Themes - Bengal

Themes

Use, customize, or create themes

2 min read 439 words

Themes are complete design packages. Use one as-is, customize it, or build your own.

Note

Do I need this? Yes when switching, customizing, or authoring themes. For a first override, see Swizzle tutorial or Customize the Default Theme.

Customize Themes

Customize existing themes without breaking updates

Theme Library Assets

Package reusable Kida components with CSS and JavaScript for Bengal themes

Theme Resolution

flowchart TB A[Request: header.html] B{Your templates/?} C{Theme templates/?} D{Bengal default?} E[Use your file] F[Use theme file] G[Use default file] A --> B B -->|Found| E B -->|Not found| C C -->|Found| F C -->|Not found| D D --> G

Your files always win. Override only what you need.

Choose Your Approach

🎨 Use Default

Effort: None

Works out of the box. Set colors via CSS variables.

✏️ Customize

Effort: Low-Medium

Override specific templates. No forking required.

🏗️ Create New

Effort: High

Full control. Start from scratch or fork existing.

Bundled Themes

Theme	Use when
`default`	You want Bengal's built-in documentation theme with no extra packages.

Bengal bundles a singledefaulttheme. For component-library themes such as the external Chirp UI theme, install the theme package and pointthemeat it; the package supplies its own templates and assets through the theme library asset contract below.

Theme authors can package reusable component systems with theme library asset contracts. Bengal will load the package templates, emit the declared CSS/JS in both dev and static builds, and warn or fail when rendered HTML references missing local assets.

Quick Reference

toml

TOML

# bengal.toml
[build]
theme = "default"

css

CSS

/* static/css/custom.css */
:root {
  --color-primary: #3b82f6;
  --color-background: #0f172a;
  --font-family-base: "Inter", sans-serif;
}

Include in your template:

html

HTML

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

Or store the path in [theme.config]and reference it:

toml

TOML

[theme.config]
custom_css = ["css/custom.css"]

Then in your template:

html

HTML

{% for css_file in theme.config.custom_css %}
<link rel="stylesheet" href="{{ asset_url(css_file) }}">
{% end %}

tree-sitter-query

TREE-SITTER-QUERY

your-project/
└── templates/
    └── partials/
        └── header.html  # Your version wins

Use bengal theme swizzle --template-path partials/header.htmlto copy the original, then modify as needed.

Theme Contents

Directory	Purpose
`templates/`	HTML templates (Kida)
`static/`	CSS, JS, images
`assets/`	Processed assets
`theme.toml`	Theme configuration

Tip

Start minimal: Override CSS variables first. Only copy templates when you need structural changes. The less you override, the easier upgrades will be.

In This Section

Customize Themes Customize existing themes without breaking updates

Theme Library Assets Package reusable Kida components with CSS and JavaScript for Bengal themes