ADR 0007 — Source-preserving Django templates over HTML¶
- Status Accepted
- Date 2026-11-17
Context¶
Django's compiled template nodes consume closing tags and comments. The formatter and verifier need complete source ranges. The existing HTML pack already provides element layout, attributes, embedded languages and whitespace handling.
Decision¶
Scan Django delimiters with byte offsets, following Django's lexer behavior. Mask template tokens in a temporary copy, parse its HTML, and combine the HTML tree with source-preserving template nodes. Group matching block tags within their HTML parent. Every returned node refers to the original source. Normalize the HTML parser's void-element nesting before grouping blocks.
Preserve inline blocks, translation messages, raw blocks, templated HTML tags and embedded scripts containing templates. Reuse the HTML rules for other content and the existing verifier for the combined tree.
Automatically select the Django pack for .html and .htm containing
template delimiters, as requested. Use in-memory contents when available.
Register .djhtml for explicit selection and expose [language.django]
options independently of [language.html].
Consequences¶
Formatting has no Django runtime dependency and can handle custom tags without importing project code. Compatibility tests use Django's lexer and renderer. Template constructs crossing HTML element boundaries currently produce a parse error and leave the file untouched. Shared delimiters can also detect Jinja or client-side templates, whose syntax may need additional support.
Alternatives considered¶
django-template-analyzer traverses compiled nodes and resolves inheritance
across templates. Retaining source syntax would still require a separate
representation. Django's internal DebugLexer provides character offsets,
but importing it at runtime would introduce a framework dependency. A small
byte scanner retains source spans directly and is tested against its output.