Swizzle and Customize the Default Theme

In this tutorial, you'll learn how to swizzle (copy) templates from Bengal's default theme into your project, customize them, and keep them updated. By the end, you'll have a personalized site that inherits from the default theme while allowing you to make targeted customizations.

Note

Who is this for? This tutorial is for developers who want to customize Bengal's default theme without forking it entirely. You should have basic familiarity with HTML and Kida templates. No prior experience with swizzling is required.

Goal

By the end of this tutorial, you will:

Understand what swizzling is and why it's useful
Discover available templates in the default theme
Swizzle specific templates to your project
Customize swizzled templates to match your needs
Track and update swizzled templates safely
Build a working customized site

Prerequisites

Python 3.14+ installed
Bengal installed (pip install bengaloruv add bengal)
A Bengal site initialized (runbengal new site mysiteif you haven't already)
Basic knowledge of HTML and Kida templates

What is Swizzling?

Swizzling is the process of copying a template from a theme into your project'stemplates/directory. Once swizzled, you can customize the template without modifying the original theme files.

Why Swizzle?

Safe customization: Modify templates without touching installed theme files
Update-friendly: Track which templates you've customized
Selective changes: Only copy what you need to change
Provenance tracking: Bengal remembers where templates came from

How It Works

When Bengal renders a page, it looks for templates in this order:

Your project →{site.root_path}/templates/(highest priority)
Installed themes → Theme packages
Bundled themes → Built-in themes likedefault

If you swizzle a template, your version intemplates/takes precedence. Everything else continues to use the theme's original templates.

Set Up Your Project

2 min

Create or use an existing Bengal site as your starting point.

Let's start with a fresh Bengal site. If you already have one, you can use it.

# Create a new Bengal site
bengal new site my-custom-site
cd my-custom-site

You should see this structure:

my-custom-site/
├── config/           # Configuration directory
│   └── _default/     # Default environment settings
├── content/          # Your markdown files
├── assets/           # CSS, JS, images
├── templates/        # Template overrides (empty initially)
└── .gitignore

Tip

Whytemplates/is empty Thetemplates/directory starts empty because Bengal uses templates from the default theme. Once you swizzle templates here, they'll override the theme versions.

2
Discover Swizzlable Templates
3 min

Explore the default theme's template structure to plan your customizations.

Before swizzling, let's see what templates are available in the default theme.
```
bengal utils theme discover
```
This lists all templates you can swizzle. You'll see output like:
```
404.html
base.html
page.html
partials/action-bar.html
partials/navigation-components.html
partials/search-modal.html
partials/search.html
...
```
Understanding Template Structure

The default theme organizes templates into:
- Root templates:base.html,page.html,404.html— Main page templates
- Partials:partials/*.html— Reusable components (navigation, search, etc.)
- Content types:blog/,doc/,autodoc/python/— Type-specific templates
What should I swizzle?
Start small: Swizzle only what you need to customize. Common starting points:
- partials/navigation-components.html— Navigation menus
- partials/search.html— Search functionality
- base.html— Site-wide layout
- page.html— Individual page layout
3
Swizzle Your First Template
2 min

Copy a theme template to your project for customization.

Let's swizzle the navigation components template. This is a good starting point because navigation is often customized.
```
bengal utils theme swizzle partials/navigation-components.html
```
You should see:
```
✓ Swizzled to /path/to/my-custom-site/templates/partials/navigation-components.html
```
Verify the Swizzle

Check that the file was created:
```
ls -la templates/partials/
```
You should seenavigation-components.htmlin your project'stemplates/partials/directory.

Check Swizzle Registry

Bengal tracks swizzled templates in.bengal/themes/sources.json. Let's see what's tracked:
```
bengal utils theme swizzle-list
```
Output:
```
- partials/navigation-components.html (from default)
```
This confirms Bengal knows where the template came from.
4
Customize Your Swizzled Template
5 min

Make targeted changes to the copied template.

Now let's customize the navigation. Opentemplates/partials/navigation-components.htmlin your editor.

Understand the Template Structure

The file contains template functions (macros) for navigation components. The exact structure depends on your theme version, but you'll typically find functions for breadcrumbs, menus, and navigation items.

To customize breadcrumbs, search for a function likebreadcrumbsor look for separator elements. The structure might look like:
```
{% def breadcrumbs(page) %}
  <nav class="breadcrumbs">
    {% for item in page.get_breadcrumbs() %}
      {% if not loop.last %}
        <a href="{{ item.url | absolute_url }}">{{ item.title }}</a>
        <span class="separator">/</span>
      {% else %}
        <span class="current">{{ item.title }}</span>
      {% end %}
    {% end %}
  </nav>
{% end %}
```
Note

Kida vs Jinja2 syntax Bengal uses Kida templates by default, but Kida can parse Jinja2 syntax. The examples here use Kida's unified{% end %}syntax, but if your theme uses Jinja2 syntax ({% endif %},{% endfor %}), that works too. See Kida syntax reference for details.

Make a Simple Change

Find the separator element and change it from/to→:
```
<span class="separator">→</span>
```
Save the file and preview your site:

Navigate to a page with breadcrumbs and verify the separator changed. The dev server automatically reloads when you save template files.

Tip

Live reload The dev server watches for file changes. Save your template and refresh the browser to see changes immediately.
5
Swizzle and Customize Multiple Templates
Optional 5 min

Apply the same pattern to additional components.

Let's swizzle the search modal and customize it.

Swizzle the Search Modal
```
bengal utils theme swizzle partials/search-modal.html
```
Customize the Search Modal

Opentemplates/partials/search-modal.htmlin your editor. Common customizations include:
- Change the placeholder text
- Modify CSS classes for styling
- Add custom search behavior or attributes
Example: Change Placeholder Text

Find the search input field (look for<input type="search">):
```

<input
  type="search"
  placeholder="Search the site..."
  class="search-input"
>
```
Change the placeholder attribute:
```
<input
  type="search"
  placeholder="Find anything..."
  class="search-input"
>
```
Verify Your Changes

Check your swizzled templates:
```
bengal utils theme swizzle-list
```
You should see both templates:
```
- partials/navigation-components.html (from default)
- partials/search-modal.html (from default)
```
6
Understand Template Inheritance
Optional 5 min

Learn a lighter-weight alternative to full swizzling.

Swizzling copies the entire template. But you can also use template inheritance to override only specific parts.

Swizzle the Base Template
```
bengal utils theme swizzle base.html
```
Use Inheritance Instead

Instead of modifying the entirebase.html, you can create a minimal override that extends the original theme template:
```

{% extends "default/base.html" %}

{# Override only the header block #}
{% block header %}
<header class="custom-header">
  <h1>{{ site.title }}</h1>
  <nav>
    {% for item in menu.main %}
    <a href="{{ item.url }}">{{ item.name }}</a>
    {% end %}
  </nav>
</header>
{% end %}

{# Everything else inherits from default/base.html #}
```
This approach:
- Keeps your template minimal (only what you override)
- Makes updates easier (most of the template stays in the theme)
- Reduces maintenance burden
Warning

Full swizzle vs. inheritance

Choose the right approach based on your needs:
- Full swizzle: Copy entire template
  - ✅ Full control over all template code
  - ❌ Harder to update when theme changes
  - Use when: You need extensive customizations or structural changes
- Inheritance: Override specific blocks only
  - ✅ Easier to maintain and update
  - ✅ Minimal code to manage
  - ❌ Limited to block-level overrides
  - Use when: You only need to customize specific sections
  Start with inheritance if possible, then swizzle if you need more control.
7
Track and Update Swizzled Templates
3 min

Keep your customizations maintainable as the theme evolves.

Bengal tracks which templates you've swizzled and whether you've modified them. This helps you update templates safely.

How Modification Detection Works

When you swizzle a template, Bengal records a checksum of the copied file. If you later modify the template locally, Bengal detects the change by comparing checksums.

Theswizzle-updatecommand only updates templates where your local file matches the original swizzled checksum (meaning you haven't modified it):
```
bengal utils theme swizzle-update
```
Output:
```
Updated: 0, Skipped (changed): 2, Missing upstream: 0
```
This means:
- Updated: 0 — No templates were updated (you've modified them)
- Skipped (changed): 2 — Two templates were skipped because you changed them
- Missing upstream: 0 — All source templates still exist
Update Conditions

Templates are updated only when all of these conditions are met:
1. The local file matches the original swizzled checksum (you haven't modified it)
2. The upstream template in the theme has changed since you swizzled it
3. The source template still exists in the theme
This prevents overwriting your customizations. Modified templates are skipped automatically.
8
Build and Test
2 min

Generate production files and verify your customizations work.

Let's build your customized site and verify everything works.

Build for Production
```
bengal build
```
This generates static files inpublic/using your swizzled templates.

Verify Customizations
1. Check navigation: Breadcrumbs should use→instead of/
2. Check search: Search placeholder should say "Find anything..."
3. Check structure: Site should render correctly
Review Build Output
```
public/
├── index.html
├── static/
│   └── css/
│       └── ...
└── ...
```
Your customizations are baked into the HTML files.

Best Practices

1. Swizzle Only What You Need

Don't swizzle everything at once. Start with one template, customize it, then move to the next.

# ✅ Good: Swizzle one at a time
bengal utils theme swizzle partials/navigation-components.html
# Customize it
# Then swizzle the next one

# ❌ Avoid: Swizzling everything
# bengal utils theme swizzle base.html
# bengal utils theme swizzle page.html
# bengal utils theme swizzle partials/*.html
# (Too many files to maintain)

2. Document Your Changes

Add comments in swizzled templates explaining why you changed something. This helps you remember the reason later and helps others understand your customizations:

{# Custom: Changed separator from '/' to '→' for better visual hierarchy #}
<span class="separator">→</span>

Comments also make it easier to re-apply changes if you need to re-swizzle a template.

3. Use Template Inheritance When Possible

If you only need to override a block, use inheritance instead of full swizzle. This keeps your templates minimal and easier to maintain:

{# ✅ Good: Override only what's needed #}
{% extends "default/base.html" %}
{% block header %}
  {# Your custom header code #}
{% end %}

{# ❌ Avoid: Copying entire template when you only need one block #}
{# This creates unnecessary maintenance burden #}

Inheritance is especially useful for:

Overriding header/footer sections
Customizing specific page blocks
Adding site-wide elements without copying entire templates

4. Keep Swizzled Templates Updated

Periodically runswizzle-updateto get bug fixes and improvements:

# Check what would be updated
bengal utils theme swizzle-update

# Review changes, then rebuild
bengal build

5. Test After Updates

After updating templates, test your site:

bengal serve
# Navigate through your site
# Verify customizations still work

Troubleshooting

Issue:FileNotFoundError: Template not found in theme chain

Solution: Verify the template path:

# List available templates
bengal utils theme discover

# Use the exact path shown
bengal utils theme swizzle partials/navigation-components.html

What You've Learned

In this tutorial, you:

✅ Discovered available templates withbengal utils theme discover
✅ Swizzled templates withbengal utils theme swizzle
✅ Customized swizzled templates to match your needs
✅ Tracked swizzled templates withbengal utils theme swizzle-list
✅ Updated templates safely withbengal utils theme swizzle-update
✅ Built a customized site using swizzled templates

Next Steps

Now that you can swizzle templates, explore further:

Theme Customization Guide — Deep dive into advanced customization techniques
Template Reference — Learn about Kida templates and available functions
Variables Reference — Discover all template variables available
Assets Guide — Customize CSS and JavaScript

Summary

Swizzling lets you customize Bengal's default theme safely:

Discover templates withbengal utils theme discover
Swizzle templates withbengal utils theme swizzle <path>
Customize swizzled templates intemplates/
Track swizzled templates withbengal utils theme swizzle-list
Update safely withbengal utils theme swizzle-update

Your customizations are preserved while you can still benefit from theme updates. Use template inheritance when possible to minimize maintenance overhead.

Swizzle and Customize the Default Theme

Goal

Prerequisites

What is Swizzling?

Why Swizzle?

How It Works

Set Up Your Project

Discover Swizzlable Templates

Swizzle Your First Template

Customize Your Swizzled Template

Swizzle and Customize Multiple Templates

Understand Template Inheritance

Track and Update Swizzled Templates

Build and Test

Best Practices

1. Swizzle Only What You Need

2. Document Your Changes

3. Use Template Inheritance When Possible

4. Keep Swizzled Templates Updated

5. Test After Updates

Troubleshooting

What You've Learned

Next Steps

Summary