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 Jinja2 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 Jinja2 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 →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:
1 2 3 4 5 6 7 8
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/,api-reference/— 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.

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 Jinja2 macros for navigation components. Let's add a simple customization: change the breadcrumb separator.

Find the breadcrumbs macro (around line 30-50) and look for the separator. It might look like:

{% macro 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>
      {% endif %}
    {% endfor %}
  </nav>
{% endmacro %}

Make a Simple Change

Change the separator from/to→:

<span class="separator">→</span>

Save the file and preview your site:

bengal serve

Navigate to a page with breadcrumbs and verify the separator changed.

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.html. You might want to:
- Change the placeholder text
- Modify the styling classes
- Add custom search behavior
For example, change the search placeholder:
1 2 3 4 5 6
 <input type="search" placeholder="Search the site..." class="search-input" >
Change it to:
1 2 3 4 5
<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:
1 2
- partials/navigation-components.html (from default) - partials/search-modal.html (from default)

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:

<!-- templates/base.html -->
{% 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>
    {% endfor %}
  </nav>
</header>
{% endblock %}

{# Everything else inherits from default::base.html #}

Warning

Full swizzle vs. inheritance

Full swizzle: Copy entire template, full control, harder to update
Inheritance: Override blocks only, easier to maintain, less control

Choose based on how much you need to customize.

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.

Check Modification Status

When you swizzle a template, Bengal records a checksum. If you modify the template locally, Bengal detects the change.

Theswizzle-updatecommand only updates templates you haven't modified:
```
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
When Templates Are Updated

Templates are only updated if:
1. The local file matches the original swizzled checksum (you haven't modified it)
2. The upstream template has changed
3. The source template still exists
This prevents overwriting your customizations.
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
1 2 3 4 5 6
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:

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

3. Use Template Inheritance When Possible

If you only need to override a block, use inheritance instead of full swizzle:

{# ✅ Good: Override only what's needed #}
{% extends "default::base.html" %}
{% block header %}...{% endblock %}

{# ❌ Avoid: Copying entire template when you only need one block #}

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 Jinja2 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.

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