Jinja2

Jinja2

Use when work primarily Jinja2 templates, server-rendered HTML, email templates, partials, or template macros.

Boundary

Use for:

• Jinja2 syntax and control flow
• template inheritance, includes, macros
• page, partial, email, component-like templates
• host-provided globals, formatting helpers, context rules
• escaping, safe, template safety boundaries

Pair with:

• python when template context from Python handlers/controllers
• htmx when templates returned as fragment responses
• design when template structure/UI boundaries need cleanup
• security when escaping, trusted HTML, untrusted context involved

Reference Map

• references/syntax.md -- expressions, conditionals, loops, filters, tests, set, comments, whitespace control
• references/templates.md -- inheritance, blocks, includes, imports, macros, call blocks, partial organization
• references/context.md -- host-provided globals, formatting helpers, translation, context boundaries
• references/safety.md -- escaping, safe, undefined handling, N+1 risks, template review guidance

Assets

• assets/main.py -- small FastAPI entrypoint wiring templates and static
• assets/templates/base.jinja -- shared page shell
• assets/templates/page/projects.jinja -- full page composing partials
• assets/templates/partials/project_list.jinja -- reusable list fragment
• assets/templates/components/badge.jinja -- small reusable template helpers
• assets/static/app.css -- minimal static styling for example app

What Stays Here

Keep this file focused on defaults and guardrails.

• keep here: syntax stance, structure defaults, safety cues
• move to refs: long syntax catalogs, inheritance patterns, host-context details
• use assets for copyable template skeletons and macro examples

Core Defaults

• keep templates focused on presentation, not business logic
• use inheritance, includes, macros to avoid repeated markup
• keep loops/conditionals readable; move heavy branching into Python
• use host formatting helpers for dates, currency, localized values when host provides them
• keep ids, classes, partial boundaries stable when templates power htmx or interactive surfaces
• default to escaped output; use safe only for trusted HTML
• give templates explicit empty states over silent blank sections

Template Structure Rules

• use base template for shared page shell when app has full pages
• use partials for repeated fragments or htmx swap targets
• use macros for small repeated structures, not giant hidden sub-apps
• keep context names boring and explicit
• keep template files close to surface they render

For deeper structure patterns, load references/templates.md.

Guardrails

• do not run DB queries or expensive calls from inside loops when host allows such access
• do not bury important formatting logic in ad hoc inline expressions
• do not use safe on user input or unknown HTML
• do not let templates become where permissions or business rules decided
• do not over-nest inheritance and includes until tracing output hard

Review Focus

• check template uses clear blocks, partials, or macros
• check formatting and translation handled consistently
• check escaping safe and intentional
• check context contract explicit enough for host app
• check heavy computation or N+1-style access should move back to Python