agent-skills/software-development/systematic-debugging/references/jinja2-template-inheritance.md

Jinja2 Template Inheritance Debugging

Silent Block Omission

Symptom: Child template's {% block X %} content is completely absent from rendered page. No error, no warning.

Root cause: Parent template (base.html) does NOT define {% block X %}{% endblock %}. Jinja2 silently ignores child blocks that don't have a corresponding parent block definition.

Detection:

# Check if parent template defines the block
grep -n "block_name" templates/base.html

# Check rendered output for the expected content
curl -s https://site/page | grep -o "expected_js_variable"

Example from ephron.ren:

• blog/templates/admin/collection_edit.html defined {% block extra_scripts %} with critical JavaScript
• blog/templates/base.html had {% block extra_styles %} and {% block content %} but NO {% block extra_scripts %}
• Result: All JavaScript for article selection was silently omitted from the page
• Other services (prompt, auth, canvas, home) all had extra_scripts defined in their base templates

Fix: Add the missing block definition to the parent template:

<!-- Before </body> -->
{% block extra_scripts %}{% endblock %}

Prevention: When creating child templates, verify the parent template defines all blocks you intend to override. Use grep to check.

Cross-service consistency check: When debugging template issues in multi-service sites, compare the base templates across all services to find missing block definitions:

for svc in blog auth canvas prompt home; do
  echo "=== $svc ==="
  grep -n "block.*endblock\|{% block" $svc/templates/base.html 2>/dev/null || \
  grep -n "block.*endblock\|{% block" $svc/templates/_design_system/page_shell.html 2>/dev/null
done