# Swizzle and Customize the Default Theme URL: /docs/tutorials/swizzle-default-theme/ Section: tutorials 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 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 bengal or uv add bengal) A Bengal site initialized (run bengal new site mysite if 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'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 → 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. 1 2 3# Create a new Bengal site bengal new site my-custom-site cd my-custom-site You should see this structure: 1 2 3 4 5 6 7my-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: 1 2 3 4 5 6 7 8404.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 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 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: 1 2 3 4 5 6 7 8 9 10 11 12{% 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 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. 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<!-- Find the input field --> <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) 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: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16<!-- 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 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. 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. Check Modification Status When you swizzle a template, Bengal records a checksum. If you modify the template locally, Bengal detects the change. The swizzle-update command 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: The local file matches the original swizzled checksum (you haven't modified it) The upstream template has changed The source template still exists This prevents overwriting your customizations. 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 1 2 3 4 5 6public/ ├── 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. 1 2 3 4 5 6 7 8 9 10# ✅ 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: 1 2{# 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: 1 2 3 4 5{# ✅ 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 run swizzle-update to get bug fixes and improvements: 1 2 3 4 5# 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: 1 2 3bengal 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: 1 2 3 4 5# 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, double colon, path) 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 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 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. -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 1843 - Reading Time: 9 minutes