Kida Syntax Reference

Complete reference for Kida template syntax, operators, and features. Kida is Bengal's default template engine, optimized for performance and free-threaded Python.

Tip

New to Kida? Start with the Kida Tutorial for a guided introduction. Most Jinja2 templates work without changes, but Kida does not support all Jinja2 features (notably{% macro %}—use{% def %}instead). If you need full Jinja2 compatibility, use the Jinja2 engine by settingtemplate_engine: jinja2in your config.

Quick Comparison: Kida vs Jinja2

Feature	Kida	Jinja2
Block endings	`{% end %}`(unified)	`{% endif %}`,`{% endfor %}`, etc.
Template variables	`{% let %}`(template-scoped)	`{% set %}`(block-scoped only)
Block variables	`{% set %}`(block-scoped)	`{% set %}`(block-scoped)
Pattern matching	`{% match %}...{% case %}`	`{% if %}...{% elif %}`chains
While loops	`{% while cond %}...{% end %}`	❌ Not available
Pipeline operator	`\|>`(left-to-right)	`\|`(right-to-left)
Optional chaining	`obj?.attr`,`obj?['key']`	❌ Not available
Null coalescing	`value ?? default`	`value \| default(...)`
Fragment caching	`{% cache key %}...{% end %}`	Requires extension
Functions	`{% def %}`(lexical scope)	`{% macro %}`(isolated scope)

Basic Syntax

Variables

Output a variable:

{{ page.title }}
{{ site.config.title }}
{{ page.content | safe }}

Comments

{# This is a comment #}
{# Multi-line
   comments work too #}

Escaping

{# HTML is escaped by default #}
{{ user_input }}  {# Escaped #}
{{ user_input | safe }}  {# Raw HTML #}
{{ user_input | e }}  {# Explicit escape #}

Control Flow

Conditionals

{% if page.draft %}
  <span class="draft">Draft</span>
{% end %}

{% if page.published %}
  Published
{% elif page.scheduled %}
  Scheduled
{% else %}
  Unpublished
{% end %}

Loops

{% for post in site.pages |> where('type', 'blog') %}
  <article>
    <h2>{{ post.title }}</h2>
    {{ post.content | safe }}
  </article>
{% end %}

Loop variables:

Variable	Description
`loop.index`	Current iteration (1-indexed)
`loop.index0`	Current iteration (0-indexed)
`loop.length`	Total number of items
`loop.first`	True on first iteration
`loop.last`	True on last iteration
`loop.revindex`	Iterations remaining (1-indexed)
`loop.cycle(...)`	Cycle through values

{% for item in items %}
  {% if loop.first %}First item{% end %}
  {% if loop.last %}Last item{% end %}
  Item {{ loop.index }} of {{ loop.length }}
  <tr class="{{ loop.cycle('odd', 'even') }}">
{% end %}

Pattern Matching

Kida's native pattern matching replaces longif/elifchains:

{% match page.type %}
  {% case "blog" %}
    <i class="icon-pen"></i> Blog Post
  {% case "doc" %}
    <i class="icon-book"></i> Documentation
  {% case "tutorial" %}
    <i class="icon-graduation-cap"></i> Tutorial
  {% case _ %}
    <i class="icon-file"></i> Page
{% end %}

With expressions:

{% match page.status %}
  {% case "published" %}
    <span class="status-published">Published</span>
  {% case "draft" %}
    <span class="status-draft">Draft</span>
  {% case _ %}
    <span class="status-unknown">Unknown</span>
{% end %}

Variables and Scoping

Scoping:{% let %}is template-scoped,{% set %}is block-scoped, and{% export %}promotes variables to template scope. See the Variables documentation for details.

Template-Scoped Variables (`{% let %}`)

Variables available throughout the entire template:

{% let site_title = site.config.title %}
{% let nav_items = site.menus.main %}

{# Available anywhere in template #}
<h1>{{ site_title }}</h1>

Block-Scoped Variables (`{% set %}`)

Variables scoped to the current block:

{% if page.published %}
  {% set status = "Published" %}
  <span>{{ status }}</span>
{% end %}
{# status not available here #}

Multi-let (Comma-Separated)

Assign multiple variables in a single{% let %}block:

{# Single-line multi-let #}
{% let a = 1, b = 2, c = 3 %}

{# Multi-line multi-let (recommended for readability) #}
{% let
    _site_title = config?.title ?? 'Untitled Site',
    _page_title = page?.title ?? config?.title ?? 'Page',
    _description = page?.description ?? '' %}

Recommended pattern for template setup:

{% extends "base.html" %}

{# Group related configuration at template start #}
{% let
    _show_sidebar = page?.sidebar ?? true,
    _show_toc = page?.toc ?? true,
    _prev = get_prev_page(page),
    _next = get_next_page(page) %}

{% block content %}
  {# Variables available throughout #}
  {% if _show_sidebar %}...{% end %}
{% end %}

Tuple Unpacking

Destructure tuples into separate variables:

{% let (title, subtitle) = (page.title, page.subtitle) %}
{% let (first, second) = get_pair() %}

Exporting from Inner Scope (`{% export %}`)

Make a variable from an inner scope available to the outer scope:

{% for post in posts %}
  {% if post.featured %}
    {% export featured_post = post %}
  {% end %}
{% end %}

{# featured_post available here #}
{{ featured_post.title }}

Template Structure

Extends

{% extends "baseof.html" %}

Blocks

{% block content %}
  <article>
    {{ page.content | safe }}
  </article>
{% endblock %}

Note: Kida uses{% endblock %}for blocks (Jinja2 compatibility), but{% end %}works too.

Includes

{% include "partials/header.html" %}
{% include "partials/footer.html" with context %}

Imports

{% import "macros.html" as macros %}
{{ macros.card(page) }}

{% from "macros.html" import card %}
{{ card(page) }}

Functions

Defining Functions (`{% def %}`)

Kida functions can access variables from their surrounding context automatically—no need to pass site config, theme settings, or other shared values as parameters:

{% let site_name = site.config.title %}

{% def card(item) %}
  <div class="card">
    <h3>{{ item.title }}</h3>
    <p>{{ item.description }}</p>
    <span>From: {{ site_name }}</span>  {# ✅ Accesses outer variable #}
  </div>
{% end %}

{# Just pass the item—site_name is available automatically #}
{{ card(page) }}

With parameters:

{% def button(text, href, class="btn") %}
  <a href="{{ href }}" class="{{ class }}">{{ text }}</a>
{% end %}

{{ button("Click me", "/page", "btn-primary") }}
{{ button("Default", "/page") }}

Calling Functions with Blocks

{% def card(item) %}
  <div class="card">
    <h3>{{ item.title }}</h3>
    {% slot %}
      {# Content passed via call block #}
    {% endslot %}
  </div>
{% end %}

{% call card(page) %}
  <p>Custom content here</p>
{% endcall %}

Filters and Pipeline

Functions vs Filters

Kida templates support both filters (transform values) and functions (standalone operations).

Filters transform a value using|or|>:

{{ page.title | upper }}                    {# Transform text #}
{{ site.pages |> where('draft', false) }}  {# Transform collection #}

Functions are called directly without a value:

{{ get_page('docs/about') }}               {# Retrieve page #}
{{ get_data('data/authors.json') }}        {# Load data #}
{{ ref('docs/getting-started') }}          {# Generate link #}

When to use which:

Filter: You have a value to transform ({{ value | filter }})
Function: You're performing an operation ({{ function() }})

See Template Functions Reference for details.

Filter Syntax

{{ text | upper }}
{{ text | truncate(100) }}
{{ text | default("N/A") }}

Pipeline Operator (`|>`)

Kida's pipeline operator provides left-to-right readability for complex filter chains:

{# Kida: Read left-to-right #}
{{ items |> where('published', true) |> sort_by('date') |> take(5) }}

{# Jinja2: Read inside-out #}
{{ items | selectattr('published') | sort(attribute='date') | first(5) }}

Chaining filters:

{{ page.content
   |> markdownify
   |> truncate(200)
   |> strip_tags }}

Tip

Use|>for chains of 3+ filters. For simple single-filter cases,|is fine:

{{ text | upper }}           {# Simple: use | #}
{{ data |> filter |> sort |> take(5) }}  {# Complex: use |> #}

Built-in Filters

String Filters

{{ text | upper }}
{{ text | lower }}
{{ text | capitalize }}
{{ text | title }}
{{ text | trim }}
{{ text | truncate(100) }}
{{ text | truncatewords(20) }}
{{ text | replace('old', 'new') }}
{{ text | slugify }}

{# Prefix/Suffix Operations #}
{{ url | trim_prefix("https://") }}    {# Remove prefix #}
{{ file | trim_suffix(".txt") }}       {# Remove suffix #}
{{ url | has_prefix("https://") }}     {# Check prefix (bool) #}
{{ file | has_suffix(".md") }}         {# Check suffix (bool) #}
{{ text | contains("error") }}         {# Check substring (bool) #}

{# Regex Extraction #}
{{ "Price: $99.99" | regex_search(r'\$[\d.]+') }}  {# "$99.99" #}
{{ "v2.3.1" | regex_search(r'v(\d+)', group=1) }} {# "2" #}
{{ "a1 b2 c3" | regex_findall(r'\d+') }}           {# ["1", "2", "3"] #}

{# Natural Language #}
{{ ["Alice", "Bob", "Charlie"] | to_sentence }}    {# "Alice, Bob, and Charlie" #}
{{ items | to_sentence(connector='or') }}          {# "A, B, or C" #}

{# Base64 Encoding #}
{{ "hello" | base64_encode }}     {# "aGVsbG8=" #}
{{ encoded | base64_decode }}     {# Decode Base64 #}

Collection Filters

{{ items |> first }}
{{ items |> last }}
{{ items | length }}
{{ items |> sort }}
{{ items |> reverse }}
{{ items |> unique }}
{{ items | join(', ') }}
{{ items |> group_by('category') }}

Type Conversion

{{ value | string }}
{{ value | int }}
{{ value | float }}
{{ value | bool }}
{{ value | list }}
{{ value | dict }}
{{ value | tojson }}

HTML/Security

{{ html | safe }}      {# Render raw HTML #}
{{ html | escape }}    {# Escape HTML #}
{{ html | e }}         {# Short form #}
{{ html | striptags }} {# Remove HTML tags #}
{{ html | plainify }}  {# Alias for striptags (Hugo compat) #}

{# Auto-link URLs #}
{{ "Visit https://example.com" | urlize }}
{# Output: Visit <a href="https://example.com">https://example.com</a> #}

{{ text | urlize(target='_blank', rel='noopener') }}  {# Open in new tab #}

Validation

{{ value | default('fallback') }}
{{ value | d('fallback') }}      {# Short form #}
{{ value | require }}            {# Raise if None #}

URL Manipulation

{# Parse URL into components #}
{% let parts = url | url_parse %}
{{ parts.scheme }}     {# "https" #}
{{ parts.host }}       {# "example.com" #}
{{ parts.path }}       {# "/docs/api" #}
{{ parts.query }}      {# "version=2" #}
{{ parts.fragment }}   {# "section" #}
{{ parts.params.q }}   {# ["search term"] #}

{# Extract query parameter #}
{{ "https://x.com?page=2" | url_param('page') }}        {# "2" #}
{{ url | url_param('missing', 'default') }}             {# "default" #}

{# Build query string from dict #}
{{ {'q': 'test', 'page': 1} | url_query }}              {# "q=test&page=1" #}

Date Filters

{# Format dates #}
{{ page.date | dateformat('%B %d, %Y') }}  {# "January 15, 2026" #}
{{ page.date | dateformat('%Y-%m-%d') }}   {# "2026-01-15" (default) #}
{{ page.date | date_iso }}                 {# ISO 8601 format #}
{{ page.date | date_rfc822 }}              {# RFC 822 for RSS feeds #}

{# Relative time #}
{{ post.date | time_ago }}    {# "2 days ago", "5 hours ago" #}
{{ post.date | days_ago }}    {# 14 (integer) #}
{{ post.date | months_ago }}  {# 3 (integer) #}
{% if post.date | days_ago < 7 %}NEW{% end %}

{# Add/subtract time #}
{{ page.date | date_add(days=7) }}               {# One week later #}
{{ now | date_add(days=-30) }}                   {# 30 days ago #}
{{ event.start | date_add(hours=2, minutes=30) }} {# 2.5 hours later #}
{{ page.date | date_add(weeks=2) }}              {# Two weeks later #}

{# Calculate difference #}
{{ end_date | date_diff(start_date) }}               {# Days between #}
{{ end_date | date_diff(start_date, unit='hours') }} {# Hours between #}
{{ end_date | date_diff(start_date, unit='all') }}   {# Dict with all units #}

Fragment Caching

Kida provides built-in fragment caching:

{% cache "sidebar-nav" %}
  {{ build_nav_tree(site.pages) }}
{% end %}

{% cache "weather", ttl="5m" %}
  {{ fetch_weather() }}
{% end %}

{% cache "posts-" ~ site.nav_version %}
  {% for post in recent_posts %}
    {{ post.title }}
  {% end %}
{% end %}

Cache keys can be:

Static strings:"sidebar"
Expressions:"posts-" ~ page.id
Variables:cache_key

TTL (Time To Live):

ttl="5m"- 5 minutes
ttl="1h"- 1 hour
ttl="30s"- 30 seconds

Automatic Block Caching

Kida automatically caches site-scoped template blocks for optimal build performance. This happens automatically—no template syntax changes required.

How it works:

Analysis: Kida analyzes your templates to identify blocks that only depend on site-wide context (not page-specific data)
Pre-rendering: These blocks are rendered once at build start
Automatic reuse: During page rendering, cached blocks are used automatically instead of re-rendering

Example:

{# base.html #}
{% block nav %}
  <nav>
    {% for page in site.pages %}
      <a href="{{ page.url }}">{{ page.title }}</a>
    {% end %}
  </nav>
{% end %}

{% block content %}
  {{ page.content | safe }}
{% end %}

Thenavblock depends only onsite.pages(site-wide), so it's automatically cached and reused for all pages. Thecontentblock depends onpage.content(page-specific), so it renders per page.

Benefits:

Significantly faster builds for navigation-heavy sites (benchmarks show 10x+ improvement for large sites)
Zero template changes — works automatically
Transparent — templates render normally, caching is invisible

Cache scope detection:

Site-scoped: Blocks that only accesssite.*,config.*, or no page-specific variables
Page-scoped: Blocks that accesspage.*or other page-specific data
Not cacheable: Blocks with non-deterministic behavior (random, shuffle, etc.)

Tip

Performance tip: Structure your templates so site-wide blocks (nav, footer, sidebar) are separate from page-specific blocks (content). Kida will automatically optimize them.

Kida-Only Features

These features are unique to Kida and not available in Jinja2:

Feature	Syntax	Purpose
Optional chaining	`?.`,`?[`	Safe access without errors
Null coalescing	`??`	Fallback for None values
Range literals	`1..10`,`1...11`	Concise iteration ranges
While loops	`{% while %}`	Condition-based iteration
Break/Continue	`{% break %}`,`{% continue %}`	Loop control

Optional Chaining

Safe navigation operators returnNoneinstead of raising errors when accessing missing attributes or keys.

Optional Attribute Access (`?.`)

Safe attribute access—returnsNoneif the object isNone:

{{ user?.profile?.name }}           {# None if user or profile is None #}
{{ page?.metadata?.author }}        {# None if page or metadata is None #}
{{ config?.theme?.colors?.primary }} {# Deep safe access #}

Optional Subscript Access (`?[`)

Safe key/index access—returnsNoneif the object isNone:

{{ data?['key'] }}                  {# None if data is None #}
{{ schema?['in'] }}                 {# Access reserved word keys safely #}
{{ items?[0] }}                     {# Safe index access #}
{{ config?['settings']?['theme'] }} {# Chained safe subscript #}

Combining with attribute access:

{{ api?.response?['data']?['items'] }}  {# Mix both operators #}
{{ user?.preferences?['theme'] ?? 'light' }}

Tip

Kida uses?[not?.[]: Unlike JavaScript which uses?.['key'], Kida uses the more concise?['key']. The pattern is simple: prefix?makes any accessor optional.

Accessor	Regular	Optional
Attribute	`.attr`	`?.attr`
Subscript	`['key']`	`?['key']`

Common Use Cases

Accessing reserved word keys (common in OpenAPI, JSON Schema):

{# OpenAPI security schemes use 'in' as a field name #}
{% let location = scheme?['in'] ?? 'header' %}
{% let api_type = spec?['type'] ?? 'apiKey' %}

Safe array access:

{% let first = items?[0] %}
{% let last = items?[-1] %}
{{ results?[0]?.name ?? 'No results' }}

Nested data structures:

{% let value = response?['data']?['users']?[0]?['email'] %}
{{ value ?? 'Not found' }}

Null Coalescing (`??`)

Fallback for None values:

{{ page.subtitle ?? page.title }}
{{ user.name ?? 'Guest' }}

Warning

Precedence gotcha: The??operator has lower precedence than|(pipe). This means filters bind to the fallback value, not the result:

{# ❌ Wrong: parses as items ?? ([] | length) #}
{{ items ?? [] | length }}

{# ✅ Correct: use default filter for filter chains #}
{{ items | default([]) | length }}

{# ✅ Also works: explicit parentheses #}
{{ (items ?? []) | length }}

When to Use Each Pattern

Pattern	Use When	Example
`??`	Simple fallback, no filtering	`{{ user.name ?? 'Anonymous' }}`
`\| default()`	Fallback followed by filters	`{{ items \\| default([]) \\| length }}`

Rule of thumb: If you need to apply filters after the fallback, use| default(). Otherwise,??is fine.

Range Literals

{% for i in 1..10 %}
  {{ i }}  {# 1, 2, 3, ..., 10 #}
{% end %}

{% for i in 1...11 %}
  {{ i }}  {# 1, 2, 3, ..., 10 (exclusive end) #}
{% end %}

{% for i in 1..10 by 2 %}
  {{ i }}  {# 1, 3, 5, 7, 9 #}
{% end %}

While Loops

Condition-based loops for scenarios where the iteration count isn't known upfront:

{% let counter = 0 %}
{% while counter < 5 %}
  {{ counter }}
  {% set counter = counter + 1 %}
{% end %}

With break and continue:

{% let i = 0 %}
{% while true %}
  {% if i >= 10 %}{% break %}{% end %}
  {% set i = i + 1 %}
  {% if i % 2 == 0 %}{% continue %}{% end %}
  {{ i }}  {# Prints odd numbers: 1, 3, 5, 7, 9 #}
{% end %}

Tip

While loops are useful for:

Processing data until a condition is met
Implementing search algorithms in templates
Building countdown/countup displays

Break and Continue

{% for item in items %}
  {% if item.hidden %}
    {% continue %}
  {% end %}
  {% if item.stop %}
    {% break %}
  {% end %}
  {{ item.title }}
{% end %}

Spaceless

Remove whitespace between HTML tags:

{% spaceless %}
  <div>
    <span>Hello</span>
    <span>World</span>
  </div>
{% endspaceless %}
{# Output: <div><span>Hello</span><span>World</span></div> #}

Operators

Arithmetic

{{ 10 + 5 }}    {# 15 #}
{{ 10 - 5 }}    {# 5 #}
{{ 10 * 5 }}    {# 50 #}
{{ 10 / 5 }}    {# 2.0 #}
{{ 10 // 5 }}   {# 2 #}
{{ 10 % 3 }}    {# 1 #}
{{ 2 ** 3 }}    {# 8 #}

Comparison

{{ a == b }}     {# Equal #}
{{ a != b }}     {# Not equal #}
{{ a < b }}      {# Less than #}
{{ a > b }}      {# Greater than #}
{{ a <= b }}     {# Less than or equal #}
{{ a >= b }}     {# Greater than or equal #}
{{ a in b }}     {# Membership #}
{{ a not in b }} {# Not in #}

Logical

{{ a and b }}
{{ a or b }}
{{ not a }}

String Concatenation

{{ "Hello" ~ " " ~ "World" }}  {# "Hello World" #}
{{ name ~ "-" ~ id }}           {# "john-123" #}

Tests

{% if value is defined %}
  {{ value }}
{% end %}

{% if value is none %}
  Default value
{% end %}

{% if value is even %}
  Even number
{% end %}

{% if value is odd %}
  Odd number
{% end %}

{% if value is divisibleby(3) %}
  Divisible by 3
{% end %}

Error Handling

Strict Mode (Default)

Kida raisesUndefinedErrorfor undefined variables:

{{ missing_var }}  {# Raises UndefinedError #}
{{ missing_var | default('N/A') }}  {# Safe: 'N/A' #}

Disabling Strict Mode

Configure inbengal.yaml:

Configuration

Kida is Bengal's default template engine. Configure inbengal.yaml:

kida:
  bytecode_cache: true      # Persistent compiled template cache (default)

Note: Strict mode (raisingUndefinedErrorfor undefined variables) is always enabled in Kida and cannot be disabled. This helps catch typos and missing context variables at render time.

Option	Default	Description
`bytecode_cache`	`true`	Cache compiled templates to disk

Switching template engines:

site:
  template_engine: jinja2   # Options: kida (default), jinja2, mako, patitas

Migration from Jinja2

Kida can parse Jinja2 syntax via compatibility mode. Most Jinja2 templates work without changes, but consider migrating to Kida syntax for pattern matching, pipeline operators, and unified block endings:

Seealso

How to Migrate from Jinja2 to Kida — Step-by-step migration guide

Key differences:

Block endings: Replace{% endif %},{% endfor %}with{% end %}
Template variables: Use{% let %}instead of{% set %}for template-wide scope
Pattern matching: Replace longif/elifchains with{% match %}...{% case %}
Pipeline: Use|>for better readability

Complete Example

{% extends "baseof.html" %}

{% let site_title = site.config.title %}
{% let recent_posts = site.pages
  |> where('type', 'blog')
  |> where('draft', false)
  |> sort_by('date', reverse=true)
  |> take(5) %}

{% block content %}
  <h1>{{ site_title }}</h1>

  {% match page.type %}
    {% case "blog" %}
      <article class="blog-post">
        <h2>{{ page.title }}</h2>
        <time>{{ page.date | dateformat('%B %d, %Y') }}</time>
        {{ page.content | safe }}
      </article>
    {% case "list" %}
      <ul>
        {% for post in recent_posts %}
          <li>
            <a href="{{ post.url }}">{{ post.title }}</a>
            <span>{{ post.date | days_ago }} days ago</span>
          </li>
        {% end %}
      </ul>
    {% case _ %}
      <div>{{ page.content | safe }}</div>
  {% end %}

  {% cache "sidebar-" ~ site.nav_version %}
    <aside>
      {{ build_sidebar(site.pages) }}
    </aside>
  {% end %}
{% endblock %}

Kida Syntax Reference

Quick Comparison: Kida vs Jinja2

Basic Syntax

Variables

Comments

Escaping

Control Flow

Conditionals

Loops

Pattern Matching

Variables and Scoping

Template-Scoped Variables ({% let %})

Block-Scoped Variables ({% set %})

Multi-let (Comma-Separated)

Tuple Unpacking

Exporting from Inner Scope ({% export %})

Template Structure

Extends

Blocks

Includes

Imports

Functions

Defining Functions ({% def %})

Calling Functions with Blocks

Filters and Pipeline

Functions vs Filters

Filter Syntax

Pipeline Operator (|>)

Built-in Filters

String Filters

Collection Filters

Type Conversion

HTML/Security

Validation

URL Manipulation

Date Filters

Fragment Caching

Automatic Block Caching

Kida-Only Features

Optional Chaining

Optional Attribute Access (?.)

Optional Subscript Access (?[)

Common Use Cases

Null Coalescing (??)

When to Use Each Pattern

Range Literals

While Loops

Break and Continue

Spaceless

Operators

Arithmetic

Comparison

Logical

String Concatenation

Tests

Error Handling

Strict Mode (Default)

Disabling Strict Mode

Configuration

Migration from Jinja2

Complete Example

See Also

Template-Scoped Variables (`{% let %}`)

Block-Scoped Variables (`{% set %}`)

Exporting from Inner Scope (`{% export %}`)

Defining Functions (`{% def %}`)

Pipeline Operator (`|>`)

Optional Attribute Access (`?.`)

Optional Subscript Access (`?[`)

Null Coalescing (`??`)