# Customize Themes

URL: /docs/theming/themes/customize/
Section: themes
Tags: themes, customization, templates, css

--------------------------------------------------------------------------------

Customize Themes Customize Bengal themes without breaking theme updates. Use theme inheritance, template overrides, and CSS customization techniques. Understand Theme Resolution Bengal resolves themes in this order: Project themes - themes/your-theme/ (highest priority) Installed themes - Installed via pip/uv Bundled themes - Built into Bengal (e.g., default) Check Active Theme 1 2 3 4 5 6 7 8# List available themes bengal utils theme list # Get theme info bengal utils theme info default # Debug theme resolution bengal utils theme debug Create a Project Theme Option 1: Start from Scratch bengal new theme my-custom-theme This creates: themes/my-custom-theme/ ├── theme.yaml ├── templates/ │ ├── base.html │ ├── page.html │ └── partials/ │ ├── header.html │ └── footer.html └── static/ ├── css/ │ └── style.css └── js/ └── main.js Configure Your Theme Edit bengal.toml: 1 2 3[theme] name = &quot;my-custom-theme&quot; default_appearance = &quot;light&quot; Override Templates Selectively Template Inheritance You don't need to copy all templates. Override only what you need: themes/my-custom-theme/templates/base.html: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16{# Extend default theme&#39;s base template #} &#123;% extends &quot;default::base.html&quot; %&#125; {# Override only the header block #} &#123;% block header %&#125; &lt;header class=&quot;custom-header&quot;&gt; &lt;h1&gt;{{ site.title }}&lt;/h1&gt; &lt;nav&gt; &#123;% for item in menu.main %&#125; &lt;a href=&quot;{{ item.url }}&quot;&gt;{{ item.name }}&lt;/a&gt; &#123;% endfor %&#125; &lt;/nav&gt; &lt;/header&gt; &#123;% endblock %&#125; {# Everything else inherits from default theme #} Partial Overrides Override specific partials: themes/my-custom-theme/templates/partials/footer.html: 1 2 3 4&lt;footer class=&quot;custom-footer&quot;&gt; &lt;p&gt;&amp;copy; {{ site.author }} {{ &quot;now&quot; | date(&quot;%Y&quot;) }}&lt;/p&gt; &lt;p&gt;Custom footer content&lt;/p&gt; &lt;/footer&gt; Bengal will use your partial instead of the theme's default. Customize CSS Method 1: Override Theme CSS Create your own CSS file that overrides theme styles: themes/my-custom-theme/static/css/custom.css: 1 2 3 4 5 6 7 8 9 10 11/* Override theme colors */ :root { --color-primary: #3498db; --color-text: #2c3e50; } /* Custom styles */ .custom-header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 2rem; } Include in your base template: themes/my-custom-theme/templates/base.html: 1 2 3 4 5&#123;% extends &quot;default::base.html&quot; %&#125; &#123;% block extra_head %&#125; &lt;link rel=&quot;stylesheet&quot; href=&quot;{{ asset_url(&#39;css/custom.css&#39;) }}&quot;&gt; &#123;% endblock %&#125; Method 2: Use CSS Variables Many themes support CSS variables. Override them: themes/my-custom-theme/static/css/overrides.css: 1 2 3 4 5 6:root { /* Override default theme variables */ --theme-primary: #3498db; --theme-secondary: #2ecc71; --theme-font-sans: &#39;Inter&#39;, sans-serif; } Theme Configuration Options Themes can expose configuration options: themes/my-custom-theme/theme.yaml: 1 2 3 4 5 6 7 8 9name: my-custom-theme version: 1.0.0 description: Customizable theme params: show_author: true show_date: true sidebar_position: left color_scheme: light Access in templates: 1 2 3&#123;% if theme.config.params.show_author %&#125; &lt;p&gt;By {{ page.author or site.author }}&lt;/p&gt; &#123;% endif %&#125; Configure in bengal.toml: 1 2 3 4 5 6 7[theme] name = &quot;my-custom-theme&quot; [theme.params] show_author = true sidebar_position = &quot;right&quot; color_scheme = &quot;dark&quot; Best Practices Don't Modify Installed Themes ❌ Bad: 1 2# Don&#39;t edit installed theme directly vim $(python -m site --user-site)/bengal/themes/default/templates/base.html ✅ Good: 1 2 3# Create project theme that extends default bengal new theme my-theme # Override only what you need Use Theme Inheritance ✅ Good: 1 2 3 4&#123;% extends &quot;default::base.html&quot; %&#125; &#123;% block header %&#125; {# Only override header #} &#123;% endblock %&#125; ❌ Bad: 1 2 3 4 5{# Copying entire base.html #} &lt;!DOCTYPE html&gt; &lt;html&gt; {# ... hundreds of lines ... #} &lt;/html&gt; Troubleshooting Warning Theme Not Found Issue: Theme 'my-theme' not found Solutions: Verify theme directory exists: themes/my-theme/ Check theme.yaml has correct name field Run bengal utils theme list to see available themes Warning Template Inheritance Not Working Issue: Changes to parent theme not reflected Solutions: Verify extends path is correct: &quot;default::base.html&quot; Check theme chain: bengal utils theme debug Clear cache: bengal clean --cache Warning CSS Not Loading Issue: Custom CSS not applying Solutions: Use asset_url() filter: {{ asset_url('css/style.css') }} Check file location: themes/your-theme/static/css/ Hard refresh: Cmd+Shift+R Info Seealso Templating — Template basics Assets — Asset pipeline Icon Reference — SVG icons and customization Variables Reference — Available template variables

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 648
- Reading Time: 3 minutes