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

1
2
3
4
5
6
7
8

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

Example: Section Navigation

1
2
3
4
5
6
7
8

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

page

The current page being rendered.

Navigation Properties

Example: Custom Breadcrumbs

1
2
3
4
5
6
7

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

Example: Prev/Next Navigation

1
2
3
4
5
6
7
8

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

Example: Related Posts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

URL Properties

Bengal provides three URL properties with clear purposes:

page.url - 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.relative_url - For comparisons and logic

• Relative URL without baseurl (e.g.,/docs/page/)
• Use for comparisons:{% if page.relative_url == '/docs/' %}
• Use for menu activation, filtering, and conditional logic

page.permalink - Backward compatibility

• Alias forurl(same value)
• Maintained for compatibility with existing themes

Example: Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

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

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

{# Both work the same #}
<a href="{{ page.url }}">Link 1</a>
<a href="{{ page.permalink }}">Link 2</a>  {# Same as page.url #}

Why This Pattern?

• Ergonomic: Templates use{{ page.url }}for display - it "just works"
• Clear:relative_urlmakes comparisons explicit
• 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.

1
2

<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.

<a href="{{ url_for(page) }}">Link</a>

dateformat(date, format)

Formats a date object.

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

get_menu(menu_name)

Retrieves a navigation menu.

1
2
3

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

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