Theme Developer Journey

Themer Quickstart

Learn to customize Bengal themes and create your own designs.

Prerequisites

Understand Theme Resolution

Bengal looks for templates in this order:

1. Your project —templates/(overrides everything)
2. Your theme —themes/your-theme/templates/
3. Installed themes — Via pip or uv
4. Default theme — Built into Bengal

You only need to override what you want to change.

Create a Custom Theme

bengal new theme my-theme

This creates:

themes/my-theme/
├── templates/
│   ├── base.html
│   ├── home.html
│   ├── page.html
│   └── partials/
│       ├── header.html
│       └── footer.html
└── assets/
    ├── css/
    │   └── style.css
    ├── js/
    │   └── main.js
    └── images/

Configure Your Theme

Updatebengal.toml:

[theme]
name = "my-theme"

Or use config/_default/theme.yamlfor split configuration:

theme:
  name: "my-theme"

Override Templates Selectively

You do not need to copy all templates. Extend the default:

{# themes/my-theme/templates/base.html #}
{% extends "base.html" %}

{% block header %}
<header class="custom-header">
    <h1>{{ site.title }}</h1>
    {% for item in menus.main %}
    <a href="{{ item.href }}">{{ item.name }}</a>
    {% end %}
</header>
{% end %}

Everything not overridden inherits from the default theme or parent theme.

Add Custom CSS

Createthemes/my-theme/assets/css/custom.css:

:root {
    --color-primary: #3498db;
    --color-text: #2c3e50;
}

.custom-header {
    background: var(--color-primary);
    padding: 2rem;
}

Include in your template:

{% block extra_head %}
<link rel="stylesheet" href="{{ asset_url('css/custom.css') }}">
{% end %}

Template Variables

Key variables available in templates (all support safe dot-notation access):

Bengal provides 80+ template functions. Common ones:

• asset_url('path')— Generate asset URLs
• url_for('path')— Generate page URLs
• get_menu('name')— Get a navigation menu
• time_ago / date_iso — Format dates ({{ page.date | time_ago }})
• truncate_chars(text, length)— Truncate text

Debug Theme Issues

# List available themes
bengal utils theme list

# Get theme info
bengal utils theme info default

# Debug theme resolution
bengal utils theme debug

# Discover installed themes
bengal utils theme discover

# Swizzle a template for customization
bengal utils theme swizzle partials/header.html

Next Steps

• Theme Customization — Deep dive into overrides
• Template Functions — All available filters and functions
• Variables Reference — Complete template variables
• Assets — CSS, JS, and image handling

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:

1. Project themes -themes/your-theme/(highest priority)
2. Installed themes - Installed via pip/uv
3. Bundled themes - Built into Bengal (e.g.,default)

Check Active Theme

# 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

Editbengal.toml:

[theme]
name = "my-custom-theme"
default_appearance = "light"

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:

{# Extend default theme's base template #}
{% 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.href }}">{{ item.name }}</a>
        {% end %}
    </nav>
</header>
{% end %}

{# Everything else inherits from default theme #}

Partial Overrides

Override specific partials:

themes/my-custom-theme/templates/partials/footer.html:

<footer class="custom-footer">
    <p>&copy; {{ site.author }} {{ "now" | date("%Y") }}</p>
    <p>Custom footer content</p>
</footer>

Bengal will use your partial instead of the theme's default.

Page Hero Templates

The page hero templates display the header section of content pages including title, breadcrumbs, description, and stats.

Template Structure

Thepage-hero/directory contains separated hero templates:

templates/partials/
├── page-hero.html           # Dispatcher (routes by hero_style)
└── page-hero/               # Separated hero templates
    ├── _macros.html         # Shared macros and helpers
    ├── index.html           # Index page hero template
    ├── element.html         # DocElement pages (modules, classes, commands)
    └── section.html         # Section-index pages (packages, CLI groups)

The dispatcher (page-hero.html) routes to the appropriate template based on page type and hero_styleconfiguration.

Override Page Hero for API Pages

To customize the hero for API documentation pages:

For element pages (modules, classes, functions, commands):

Overridepartials/page-hero/element.htmlto customize the hero for API documentation elements:

{# themes/my-theme/templates/partials/page-hero/element.html #}
{% from 'partials/page-hero/_macros.html' import hero_element %}

{# Use the macro with custom parameters #}
{{ hero_element(element, params, theme) }}

{# Or create a completely custom hero #}
<div class="page-hero">
  <div class="page-hero__badges">
    {% include 'autodoc/python/partials/badges.html' %}
  </div>
  <h1 class="page-hero__title page-hero__title--code">
    <code>{{ element.qualified_name }}</code>
  </h1>
  {% if element.description %}
  <div class="page-hero__description">
    {{ element.description | markdownify | safe }}
  </div>
  {% end %}
</div>

For section-index pages:

Overridepartials/page-hero/section.htmlto customize section index heroes:

{# themes/my-theme/templates/partials/page-hero/section.html #}
{% from 'partials/page-hero/_macros.html' import hero_section %}

{# Use the macro #}
{{ hero_section(section, params, theme) }}

{# Or create a custom section hero #}
<div class="page-hero">
  <h1 class="page-hero__title">{{ section.title }}</h1>
  {% let desc = section.metadata.description %}
  {% if desc %}
  <div class="page-hero__description">
    {{ desc | markdownify | safe }}
  </div>
  {% end %}
</div>

Using hero_context

For CLI reference sections, pass explicit context to avoid URL sniffing:

{# In autodoc/cli/section-index.html #}
{% let hero_context = {'is_cli': true} %}
{% include 'partials/page-hero/section.html' %}

The hero_context.is_cliflag controls whether stats display:

• true: "X Groups, Y Commands"
• false: "X Packages, Y Modules"

Template Data Access Patterns

Element templates receive aDocElementdataclass—use attribute access:

• element.qualified_name
• element.description
• element.children
• element.source_file

Section templates receive aSectionobject—use attribute access:

• section.title(section title)
• section.metadata.description(safe access, returns empty string if missing)
• section.sorted_pages(sorted child pages)
• section.sorted_subsections(sorted child sections)

Customize CSS

Method 1: Override Theme CSS

Create your own CSS file that overrides theme styles:

themes/my-custom-theme/static/css/custom.css:

/* 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:

{% extends "default/base.html" %}

{% block extra_head %}
<link rel="stylesheet" href="{{ asset_url('css/custom.css') }}">
{% end %}

Method 2: Use CSS Variables

Many themes support CSS variables. Override them:

themes/my-custom-theme/static/css/overrides.css:

:root {
    /* Override default theme variables */
    --theme-primary: #3498db;
    --theme-secondary: #2ecc71;
    --theme-font-sans: 'Inter', sans-serif;
}

Theme Configuration Options

Themes can expose configuration options in two ways:

Theme-Level Configuration (theme.yaml)

Define default configuration in your theme'stheme.yamlfile:

themes/my-custom-theme/theme.yaml:

name: my-custom-theme
version: 1.0.0

# Custom configuration options
show_author: true
show_date: true
sidebar_position: left
color_scheme: light

Site-Level Overrides (bengal.toml)

Override theme defaults in your site'sbengal.toml:

[theme]
name = "my-custom-theme"

# Override theme config values
show_author = true
sidebar_position = "right"
color_scheme = "dark"

Accessing Configuration in Templates

Access theme configuration usingtheme.get()or direct property access:

{# Using theme.get() method (recommended) #}
{% if theme.get('show_author', false) %}
<p>By {{ page.author or site.author }}</p>
{% end %}

{# Direct config key access #}
{% if theme.config.show_author %}
<p>By {{ page.author or site.author }}</p>
{% end %}

Note: All keys in the [theme] section are accessible via theme.get('key') (with default) or theme.config.key(direct access).

Best Practices

Don't Modify Installed Themes

❌ Bad:

# Don't edit installed theme directly
vim $(python -m site --user-site)/bengal/themes/default/templates/base.html

✅ Good:

# Create project theme that extends default
bengal new theme my-theme
# Override only what you need

Use Theme Inheritance

✅ Good:

{% extends "default/base.html" %}
{% block header %}
  {# Only override header #}
{% end %}

❌ Bad:

{# Copying entire base.html #}
<!DOCTYPE html>
<html>
  {# ... hundreds of lines ... #}
</html>

Troubleshooting

Navigation with NavTree

Bengal provides a pre-computed navigation tree for efficient template rendering. Useget_nav_tree(page)to access the navigation structure.

Basic Usage

<nav class="sidebar">
  {% for item in get_nav_tree(page) %}
    <a href="{{ item.href }}"
       {% if item.is_current %}class="active"{% end %}
       {% if item.is_in_trail %}class="in-trail"{% end %}>
      {{ item.title }}
    </a>

    {% if item.has_children %}
      <ul>
        {% for child in item.children %}
          <li>
            <a href="{{ child.href }}">{{ child.title }}</a>
          </li>
        {% end %}
      </ul>
    {% end %}
  {% end %}
</nav>

NavNode Properties

Each navigation node provides:

Scoped Navigation

For section-specific navigation (e.g., docs-only sidebar):

{% let root = page._section.root if page._section else none %}
{% for item in get_nav_tree(page, root_section=root) %}
  <a href="{{ item.href }}">{{ item.title }}</a>
{% end %}

Benefits

• Performance: O(1) lookup via cached structure (<1ms render overhead)
• Simplicity: Single function call replaces version-filtering boilerplate
• Consistency: Pre-computed structure ensures consistent navigation across pages
• Version-aware: Automatic version filtering and shared content injection

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.

Goal

By the end of this tutorial, you will:

1. Understand what swizzling is and why it's useful
2. Discover available templates in the default theme
3. Swizzle specific templates to your project
4. Customize swizzled templates to match your needs
5. Track and update swizzled templates safely
6. Build a working customized site

Prerequisites

• Python 3.14+ installed
• Bengal installed (pip install bengal or uv add bengal)
• A Bengal site initialized (runbengal new site mysiteif 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'stemplates/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:

1. Your project →{site.root_path}/templates/(highest priority)
2. Installed themes → Theme packages
3. Bundled themes → Built-in themes likedefault

If you swizzle a template, your version intemplates/takes precedence. Everything else continues to use the theme's original templates.

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 runswizzle-updateto 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

# List available templates
bengal utils theme discover

# Use the exact path shown
bengal utils theme swizzle partials/navigation-components.html

What You've Learned

In this tutorial, you:

1. ✅ Discovered available templates withbengal utils theme discover
2. ✅ Swizzled templates withbengal utils theme swizzle
3. ✅ Customized swizzled templates to match your needs
4. ✅ Tracked swizzled templates withbengal utils theme swizzle-list
5. ✅ Updated templates safely withbengal utils theme swizzle-update
6. ✅ 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 withbengal utils theme discover
• Swizzle templates withbengal utils theme swizzle <path>
• Customize swizzled templates intemplates/
• Track swizzled templates withbengal utils theme swizzle-list
• Update safely withbengal 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.

Asset Pipeline

Bengal processes your CSS, JavaScript, images, and fonts with optional minification and fingerprinting.

How Assets Flow

Asset Locations

Quick Reference

# bengal.toml
[assets]
minify = true
optimize = true
fingerprint = true   # main.css → main.a1b2c3.css

{# Basic asset URL (function syntax) #}
<link rel="stylesheet" href="{{ asset_url('css/main.css') }}">

{# Fingerprinting is automatic when enabled in config #}
{# Outputs: /assets/css/main.a1b2c3.css #}

{# Images #}
<img src="{{ asset_url('images/logo.png') }}" alt="Logo">

{# Access assets co-located with current page #}
{% for image in page.resources.match("*.jpg") %}
  <img src="{{ image.rel_permalink }}" alt="{{ image.title }}">
{% end %}

Icons

Bengal includes a comprehensive Icon Reference powered by Phosphor Icons. Use inline icons in content with{icon}name`` syntax:

{icon}`check:24:icon-success` Task complete!

For custom icons, place SVG files in themes/your-theme/assets/icons/. See the Icon Reference for the full gallery and customization options.

Template Cookbook

Practical examples showing how to accomplish common tasks with Bengal's templating system.

Content Queries

Work with pages, sections, and taxonomies.

Page Features

Add features to individual pages.

Quick Reference

The Essentials

{# Get pages from a section #}
{% let posts = site.pages |> where('section', 'blog') %}

{# Sort by date, newest first #}
{% let recent = posts |> sort_by('date', reverse=true) %}

{# Limit to 5 #}
{% let latest = recent |> limit(5) %}

{# Or chain it all #}
{% let latest = site.pages
  |> where('section', 'blog')
  |> sort_by('date', reverse=true)
  |> limit(5) %}

Common Filters

Both\|> (Kida pipeline) and \| (Jinja-style) work. Examples use \|>for consistency.

See Template Functions for the complete reference.

Show Reading Time

Display estimated reading time using Bengal'sreading_timeproperty or filter.

The Pattern

Use the page property (recommended)

<span class="reading-time">
  {{ page.reading_time }} min read
</span>

Use the filter on content

<span class="reading-time">
  {{ page.content | reading_time }} min read
</span>

Both approaches calculate reading time at 200 words per minute by default.

What's Happening

Variations

<span>{{ page.content | word_count }} words · {{ page.content | reading_time }} min read</span>

{# 250 words per minute instead of 200 #}
{% let words = page.content | word_count %}
{% let minutes = (words / 250) | round(0, 'ceil') | int %}

<span>{{ minutes }} min read</span>

{% let minutes = page.content | reading_time %}

<span class="reading-time">
{% match minutes %}
  {% case m if m < 1 %}
    Quick read
  {% case 1 %}
    1 min read
  {% case m %}
    {{ m }} min read
{% end %}
</span>

{% let minutes = page.metadata.reading_time ?? page.content | reading_time %}

---
title: Complex Technical Guide
reading_time: 25  # Override calculated time
---

List Recent Posts

Display the most recent posts from a section using Bengal's query filters.

The Pattern

{% let posts = site.pages
  |> where('section', 'blog')
  |> where('draft', false)
  |> sort_by('date', reverse=true)
  |> limit(5) %}

<ul class="recent-posts">
{% for post in posts %}
  <li>
    <a href="{{ post.href }}">{{ post.title }}</a>
    <time>{{ post.date | date('%B %d, %Y') }}</time>
  </li>
{% end %}
</ul>

What's Happening

Variations

{# All non-draft pages, any section #}
{% let recent = site.pages
  |> where('draft', false)
  |> sort_by('date', reverse=true)
  |> limit(10) %}

{% let posts = site.pages |> where('section', 'blog') |> sort_by('date', reverse=true) %}
{% let featured = posts |> first %}
{% let rest = posts |> offset(1) |> limit(4) %}

<div class="featured">
  <h2>{{ featured.title }}</h2>
  <p>{{ featured.description }}</p>
</div>

<ul class="more-posts">
{% for post in rest %}
  <li><a href="{{ post.href }}">{{ post.title }}</a></li>
{% end %}
</ul>

{# In a sidebar, show recent posts excluding the current one #}
{% let others = site.pages
  |> where('section', 'blog')
  |> sort_by('date', reverse=true)
  |> limit(6) %}

{% for post in others if post._path != page._path %}
  <a href="{{ post.href }}">{{ post.title }}</a>
{% end %}

Templating

Bengal's template system uses Kida as the default engine, with support for Jinja2 and custom engines.

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

Template Lookup Order

Bengal searches: Your project → Theme → Bengal defaults

Quick Start

{# 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

Template Inheritance

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

Choose Your Engine

Kida is the default. To use a different engine, configurebengal.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 theTemplateEnvironmentprotocol:

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.

Template Functions

Bengal provides 80+ template functions and filters organized by category.

Functions vs Filters

Bengal provides filters (transform values) and functions (standalone operations).

Filters use the pipe operator:

{{ text | upper }}
{{ pages |> where('draft', false) |> sort_by('date') }}

Functions are called directly:

{{ get_page('docs/about') }}
{{ get_data('data/config.json') }}
{{ ref('docs/getting-started') }}

See Template Functions Reference for complete explanation.

Function Categories

Quick Examples

Filter Pages

{% let posts = site.pages
  |> where('type', 'blog')
  |> where('draft', false)
  |> sort_by('date', reverse=true)
  |> limit(10) %}

Build Navigation

{% let docs = get_section('docs') %}
{% let crumbs = get_breadcrumbs(page) %}

Cross-Reference

{{ ref('docs/getting-started') }}
{{ ref('docs/api', 'API Reference') }}

Theme Variables

This reference lists all variables, objects, and functions available in Bengal templates.

Global Objects

These variables are available in all templates.

site

The global site object.

section

Available on index pages (_index.md) and doc-type pages.

Example: Auto-Generated Child Cards

<div class="child-cards">
  {% for subsection in section.subsections %}
    <a href="{{ subsection.index_page.href }}" class="card">
      <h3>{{ subsection.title }}</h3>
      <p>{{ subsection.metadata.description }}</p>
    </a>
  {% end %}
</div>

Example: Section Navigation

<nav class="section-nav">
  <h4>In this section:</h4>
  <ul>
    {% for page in section.sorted_pages %}
      <li><a href="{{ page.href }}">{{ page.title }}</a></li>
    {% end %}
  </ul>
</nav>

page

The current page being rendered.

Navigation Properties

Example: Custom Breadcrumbs

<nav class="breadcrumbs">
  <a href="/">Home</a>
  {% for ancestor in page.ancestors %}
    > <a href="{{ ancestor.href }}">{{ ancestor.title }}</a>
  {% end %}
  > <span>{{ page.title }}</span>
</nav>

Example: Prev/Next Navigation

<nav class="prev-next">
  {% if page.prev_in_section %}
    <a href="{{ page.prev_in_section.href }}">← {{ page.prev_in_section.title }}</a>
  {% end %}
  {% if page.next_in_section %}
    <a href="{{ page.next_in_section.href }}">{{ page.next_in_section.title }} →</a>
  {% end %}
</nav>

Example: Related Posts

{% if page.related_posts %}
<aside class="related">
  <h3>Related Articles</h3>
  <ul>
    {% for post in page.related_posts[:5] %}
      <li><a href="{{ post.href }}">{{ post.title }}</a></li>
    {% end %}
  </ul>
</aside>
{% end %}

URL Properties

Bengal provides two URL properties with clear purposes:

page.href - Primary property for display

• Automatically includes baseurl (e.g.,/bengal/docs/page/)
• Use in<a href>, <link>, <img src>attributes
• Works correctly for all deployment scenarios (GitHub Pages, Netlify, S3, etc.)

page._path - For comparisons and logic

• Site-relative URL without baseurl (e.g.,/docs/page/)
• Use for comparisons:{% if page._path == '/docs/' %}
• Use for menu activation, filtering, and conditional logic
• NEVER use in template href attributes

Example: Usage

{# Display URL (includes baseurl) #}
<a href="{{ page.href }}">{{ page.title }}</a>

{# Comparison (without baseurl) #}
{% if page._path == '/docs/' %}
  <span class="active">Current Section</span>
{% end %}

{# url_for() also works for URL generation #}
<a href="{{ url_for(page) }}">{{ page.title }}</a>

Why This Pattern?

• Ergonomic: Templates use/bengal/docs/reference/theme-variables/for display - it "just works"
• Clear:_pathmakes comparisons explicit (without baseurl)
• No wrappers: Page objects handle baseurl via their_sitereference
• Works everywhere: Supports file://, S3, GitHub Pages, Netlify, Vercel, etc.

Global Functions

Functions available in all templates.

asset_url(path)

Generates a fingerprint-aware URL for an asset.

<link rel="stylesheet" href="{{ asset_url('css/style.css') }}">
<!-- Outputs: /assets/css/style.a1b2c3d4.css -->

url_for(page_or_slug)

Generates a URL for a page object or slug. Applies baseurl automatically.

<a href="{{ url_for(page) }}">Link</a>
<a href="{{ url_for('/docs/getting-started/') }}">Getting Started</a>

dateformat(date, format)

Formats a date object.

{{ dateformat(page.date, "%B %d, %Y") }}

get_menu(menu_name)

Retrieves a navigation menu.

{% for item in get_menu('main') %}
  <a href="{{ item.url }}">{{ item.name }}</a>
{% end %}

Template Helpers

Bengal includes categorized helper modules:

• Strings:truncate, slugify, markdownify
• Collections:where, group_by, sort_by
• Dates:time_ago, date_iso
• Images:image_processed, image_url
• Taxonomies:related_posts, popular_tags