# Templating URL: /bengal/docs/build-sites/customize/templating/ Section: templating Tags: persona-themer -------------------------------------------------------------------------------- Templating Bengal's template system uses Kida as the default engine, with support for Jinja2 and custom engines. Note Note Do I need this? Yes when writing or overriding HTML templates. Skip if you only write Markdown — see Authoring. New to templates? Start with Themer Quickstart. File Functions vs Filters Quick Reference One-page guide to when to use functions vs filters File Template Functions Quick overview of filters and functions available in templates Image Processing Resize, crop, and optimize images in templates File Bring Your Own Template Engine Implement a custom template engine with full access to Bengal's 200+ template functions, filters, and tests Template Engines Kida (local reference) — Bengal's native template engine (default). Unified {% end %} blocks, pattern matching, pipeline operators Jinja2 — Industry-standard engine with excellent documentation and tooling Custom engines — Bring your own via the plugin API Tip Tip Kida is Jinja2-compatible: Your existing Jinja2 templates work without changes. Use Kida-specific features incrementally. Template Lookup Order flowchart LR A[Page Request] --> B{templates/ ?} B -->|Found| C[Use Your Template] B -->|Not Found| D{Theme templates/ ?} D -->|Found| E[Use Theme Template] D -->|Not Found| F[Use Bengal Default] Bengal searches: Your project → Theme → Bengal defaults Quick Start Basic Template Base Layout Partial {# templates/layouts/single.html #} {% extends "baseof.html" %} {% block content %} <article> <h1>{{ page.title }}</h1> {{ page.content | safe }} </article> {% end %} {# templates/baseof.html #} <!DOCTYPE html> <html> <head> <title>{% block title %}{{ page.title }}{% end %}</title> </head> <body> {% block header %}{% include "./partials/header.html" %}{% end %} {% block content %}{% end %} {% block footer %}{% include "./partials/footer.html" %}{% end %} </body> </html> {# templates/partials/header.html #} <header> <nav> {% for item in site.menus.main %} <a href="{{ item.href }}">{{ item.title }}</a> {% end %} </nav> </header> Key Concepts Concept Syntax Purpose Extends {% extends "base.html" %} Inherit from parent template Block {% block name %}...{% end %} Replaceable section Include {% include "./partial.html" %} Insert another template Variable Templating Output a value Filter {{ text \| truncate(100) }} Transform a value Kida resolves ./ and ../ relative template paths from the current template. For shared component libraries, configure kida.template_aliases and include templates with @alias/ prefixes such as {% include "@components/card.html" %}. Template Inheritance flowchart TB A["baseof.html<br/>(blocks: head, content, footer)"] B["single.html<br/>(extends baseof)"] C["list.html<br/>(extends baseof)"] D["doc.html<br/>(extends single)"] A --> B A --> C B --> D Kida Features Kida is Bengal's default template engine: Unified syntax: {% end %} closes all blocks (no more {% end %}, {% end %}) Pattern matching: {% match %}...{% case %} for cleaner conditionals Pipeline operator: |> for readable filter chains Fragment caching: Built-in {% cache %} directive Jinja2 compatible: Existing Jinja2 templates work without changes Kida Syntax Reference Complete Kida syntax documentation Note Kida Tutorial Learn Kida from scratch Code Kida How-Tos Common Kida tasks and patterns Migrate from Jinja2 Convert Jinja2 templates to Kida Choose Your Engine Kida is the default. To use a different engine, configure bengal.toml (or config/_default/site.yaml): site: template_engine: jinja2 # Options: kida (default), jinja2, mako Custom Engines (BYOR) Bring your own template engine via the protocol API. Your engine automatically gets all 80+ template functions if it satisfies the TemplateEnvironment protocol: from bengal.rendering.engines import register_engine from bengal.rendering.template_functions import register_all class MyEngine: def __init__(self, site): self.site = site self.template_dirs = [site.root_path / "templates"] # Environment must have globals, filters, tests dicts self._env = MyEnvironment() # Automatically get all 80+ template functions! register_all(self._env, site) def render_template(self, name: str, context: dict) -> str: # Your implementation ... register_engine("myengine", MyEngine) Then configure: site: template_engine: myengine See Bring Your Own Template Engine for the complete guide. Tip Tip Override sparingly: You only need to create templates you want to customize. Use bengal theme swizzle --template-path <template> to copy a template for customization. Let the rest fall through to theme defaults. -------------------------------------------------------------------------------- Metadata: - Author: lbliii - Word Count: 635 - Reading Time: 3 minutes