bengal-template-fix

name	bengal-template-fix
description	Fixes common Bengal template errors and applies safe patterns. Use when templates fail with undefined variables, href vs path issues, baseurl, or config access.

Bengal Template Fix

Fix common Bengal template errors and apply safe patterns for Kida/Jinja templates.

Quick Reference

Old Pattern	New Pattern	Why
page.metadata.get('key')	params.key	ParamsContext returns '' for missing keys
site.config.get('key')	config.key	ConfigContext has safe dot access
{% if x is defined %}	{% if x %}	ChainableUndefined handles this
site.data.resume.get('name')	site.data.resume.name	DotDict returns '' for missing keys
Raw dict in loop	item | safe_access	Wrap for safe nested access

href vs path (Baseurl Footgun)

Critical: Use href (includes baseurl) for link URLs, not path or _path. Using _path breaks GitHub Pages project sites.

Use case	Prefer	Avoid
Link URLs, <a href="...">	href	path, _path
Pagination base URLs	href	path, _path
Current-page checks	_path	href
Cache keys	_path	href

{# Correct - href first for links #}
<a href="{{ page.href ?? page._path }}">...</a>
<a href="{{ section.href ?? section._path }}">...</a>

{# Wrong - breaks on subpath deployments #}
<a href="{{ page._path ?? page.href }}">...</a>

Safe Context Access

Use dot notation; context wrappers return '' for missing keys:

{{ params.description }}
{{ params.author }}
{{ config.baseurl }}
{{ theme.hero_style }}
{{ section.title }}

Safe Data File Access

site.data returns DotDict; use dot notation:

{% set resume = site.data.resume %}
{{ resume.name or page.title }}
{{ resume.contact.email }}

For loops over lists of dicts, wrap with | safe_access:

{% for job in resume.experience %}
  {% set job = job | safe_access %}
  <h3>{{ job.title }}</h3>
  <p>{{ job.company }}</p>
{% endfor %}

Safe Iteration Over Frontmatter Collections

Tags and link collections can be malformed. Use guards:

{% let safe_tags = tags ?? [] %}
{% for tag in safe_tags %}
  {% if tag %}
  <a href="/tags/{{ tag }}">{{ tag }}</a>
  {% end %}
{% endfor %}

Checklist

• Use params.x instead of page.metadata.get('x')
• Use config.x instead of site.config.get('x')
• Use | safe_access for raw dicts from site.data
• Links use href ?? _path (href first)
• Iterating over tags/link collections: use ?? [] and {% if item %}

Additional Resources

See references/SAFE_PATTERNS.md for the full guide including URL generation, template inheritance, and Kida-specific patterns.