# Template Formatter

URL: /docs/advanced/formatter/
Section: advanced
Tags: advanced, formatter, tooling

--------------------------------------------------------------------------------

Template Formatter Kida includes an opinionated template formatter that enforces consistent whitespace, indentation, and tag spacing across your templates. No other Python template engine ships with a built-in formatter. Quick Start Format all templates in a directory: kida fmt templates/ Format a single file: kida fmt templates/page.html Check formatting without modifying files (useful in CI): kida fmt --check templates/ What It Does The formatter applies six rules to every template: Rule Before After Tag spacing &#123;%if x%&#125; &#123;% if x %&#125; Output spacing &#123;&#123; expr &#125;&#125; &#123;&#123; expr &#125;&#125; Comment spacing {#note#} {# note #} Block indentation Flat or inconsistent Indented by configured amount Trailing whitespace &lt;div&gt; &lt;div&gt; Blank line normalization 3+ consecutive blank lines Max 1 consecutive blank line Final newline Missing or present Always present Tag Spacing The formatter normalizes spacing inside all three tag types. Whitespace control markers (-) are preserved: {# Before #} &#123;%- if user -%&#125;{{user.name}}&#123;%endif%&#125; {# After #} &#123;%- if user -%&#125;{{ user.name }}&#123;% endif %&#125; Block Indentation Block bodies are indented by the configured amount (default: 2 spaces). The formatter recognizes all Kida block-opening keywords: if, for, block, while, with, def, region, call, capture, cache, filter, match, spaceless, embed, raw, push, globals, imports, unless, fragment Continuation keywords (else, elif, empty, case) are aligned with their opening tag, and their bodies are indented: &#123;% if user.is_admin %&#125; &lt;span&gt;Admin&lt;/span&gt; &#123;% elif user.is_staff %&#125; &lt;span&gt;Staff&lt;/span&gt; &#123;% else %&#125; &lt;span&gt;User&lt;/span&gt; &#123;% endif %&#125; Configuration The format_template function accepts three options: Parameter Type Default Description indent int 2 Number of spaces per indentation level max_blank_lines int 1 Maximum consecutive blank lines allowed normalize_tag_spacing bool True Normalize spacing inside &#123;% %&#125;, &#123;&#123; &#125;&#125;, and {# #} tags from kida.formatter import format_template formatted = format_template( source, indent=4, # 4 spaces per level max_blank_lines=2, # Allow up to 2 consecutive blank lines normalize_tag_spacing=True, ) Programmatic API Import format_template directly for build scripts, pre-commit hooks, or editor integrations: from kida.formatter import format_template source = open(&quot;templates/page.html&quot;).read() formatted = format_template(source) if source != formatted: open(&quot;templates/page.html&quot;, &quot;w&quot;).write(formatted) print(&quot;Formatted page.html&quot;) CI Integration Use the --check flag to fail CI when templates are not formatted. This does not modify any files — it only reports whether formatting changes are needed: kida fmt --check templates/ A non-zero exit code means at least one file needs formatting. Pair this with your existing linting step: # GitHub Actions example - name: Check template formatting run: kida fmt --check templates/ Before and After Inconsistent spacing and flat indentation Before: &#123;%block sidebar%&#125; &lt;aside&gt; &#123;%if categories%&#125; &lt;ul&gt; &#123;%for cat in categories%&#125; &lt;li&gt;{{cat.name}}&lt;/li&gt; &#123;%endfor%&#125; &lt;/ul&gt; &#123;%endif%&#125; &lt;/aside&gt; &#123;%endblock%&#125; After: &#123;% block sidebar %&#125; &lt;aside&gt; &#123;% if categories %&#125; &lt;ul&gt; &#123;% for cat in categories %&#125; &lt;li&gt;{{ cat.name }}&lt;/li&gt; &#123;% endfor %&#125; &lt;/ul&gt; &#123;% endif %&#125; &lt;/aside&gt; &#123;% endblock %&#125; Whitespace control markers preserved Before: &#123;%- for item in items -%&#125; {{-item.name-}} &#123;%-endfor-%&#125; After: &#123;%- for item in items -%&#125; {{- item.name -}} &#123;%- endfor -%&#125; See Also Static Analysis — Analyze templates for dependencies and caching potential Template Type Checking — Validate template context with &#123;% template %&#125; declarations

--------------------------------------------------------------------------------

Metadata:
- Word Count: 505
- Reading Time: 3 minutes