# Swizzle and Customize the Default Theme URL: /docs/tutorials/theming/swizzle-default-theme/ Section: theming Tags: tutorial, theming, templates, customization -------------------------------------------------------------------------------- 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 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 bengal or uv add bengal) A Bengal site initialized (run bengal new site mysite if 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's templates/ 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 like default If you swizzle a template, your version in templates/ takes precedence. Everything else continues to use the theme's original templates. 1Set Up Your Project2 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 Tip Why templates/ is empty The templates/ directory starts empty because Bengal uses templates from the default theme. Once you swizzle templates here, they'll override the theme versions. 2Discover Swizzlable Templates3 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 Info 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 3Swizzle Your First Template2 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 see navigation-components.html in your project's templates/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. 4Customize Your Swizzled Template5 min Make targeted changes to the copied template. Now let's customize the navigation. Open templates/partials/navigation-components.html in 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 like breadcrumbs or 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 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 Tip Live reload The dev server watches for file changes. Save your template and refresh the browser to see changes immediately. 5Swizzle and Customize Multiple TemplatesOptional 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 Open templates/partials/search-modal.html in 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">): <!-- Find the input field --> <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) 6Understand Template InheritanceOptional 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 entire base.html, you can create a minimal override that extends the original theme template: <!-- 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> {% 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 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. 7Track and Update Swizzled Templates3 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. The swizzle-update command 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: The local file matches the original swizzled checksum (you haven't modified it) The upstream template in the theme has changed since you swizzled it The source template still exists in the theme This prevents overwriting your customizations. Modified templates are skipped automatically. 8Build and Test2 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 in public/ using your swizzled templates. Verify Customizations Check navigation: Breadcrumbs should use → instead of / Check search: Search placeholder should say "Find anything..." 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 run swizzle-update to 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 Warning Template Not Found 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 Warning Changes Not Appearing Issue: Customizations don't show up after swizzling Solutions: Clear cache: bengal clean --cache Restart dev server: Stop and restart bengal serve Check file location: Ensure template is in templates/ (not themes/) Warning Swizzle Update Overwrites Changes Issue: swizzle-update overwrote your customizations Solution: This shouldn't happen if you've modified the file. If it does: Check .bengal/themes/sources.json for the checksum Restore from git if you use version control Re-apply your customizations Warning Template Inheritance Not Working Issue: {% extends "default/base.html" %} doesn't work Solutions: Verify theme name: Use bengal utils theme info default to confirm Check syntax: Use "default/base.html" format (theme name, forward slash, template path) Verify template exists: Use bengal utils theme discover to list available templates Clear cache: bengal clean --cache What You've Learned In this tutorial, you: ✅ Discovered available templates with bengal utils theme discover ✅ Swizzled templates with bengal utils theme swizzle ✅ Customized swizzled templates to match your needs ✅ Tracked swizzled templates with bengal utils theme swizzle-list ✅ Updated templates safely with bengal 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 with bengal utils theme discover Swizzle templates with bengal utils theme swizzle <path> Customize swizzled templates in templates/ Track swizzled templates with bengal utils theme swizzle-list Update safely with bengal 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. -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 2059 - Reading Time: 10 minutes