nnJinja templates, by default, can introduce unwanted whitespace (extra lines, spaces, or tabs) into your rendered HTML. This often happens around block tags like {% if %} or {% for %}, which, when on their lines, leave behind blank lines. Jinja provides powerful configuration options and manual controls to manage this whitespace, ensuring your output is clean and precisely formatted. This guide covers the various ways to handle whitespace, from global settings to per-tag controls.nn

---

nn

Automatic Whitespace Stripping

nJinja offers two key configuration options that automatically manage whitespace around block tags: trim_blocks and lstrip_blocks.n

n
• trim_blocks: When enabled, this option automatically removes the first newline after a block tag. This is particularly useful for preventing the extra blank lines that appear after tags like {% if True %}. With trim_blocks enabled, the newline after the closing {% endif %} is also removed.

n

• lstrip_blocks: This option strips all leading tabs and spaces from the beginning of a line up to the start of a block tag. It only works if there are no other characters on the line before the block tag.

n

nWith both trim_blocks and lstrip_blocks enabled, a template like this:n

<div>n    {% if True %}n        yayn    {% endif %}n</div>

nWill render cleanly, completely removing the blank lines and indentation around the if block:n

<div>n        yayn</div>

nIf these options are disabled (the default), the blank lines and indentation are preserved, often resulting in messy output. The yay would be wrapped in empty lines and extra indentation.nn

---

nn

Manual Whitespace Control with - and +

nJinja also gives you fine-grained control over whitespace on a per-tag basis using minus (-) and plus (+) signs. These symbols act as overrides for the default or configured behavior.n

The Minus (-) Sign

nAdding a minus sign to the start or end of a tag manually strips whitespace.n

n
• {%- strips all whitespace (spaces, tabs, newlines) before the tag.

n

• -%} strips all whitespace (spaces, tabs, newlines) after the tag.

n

nThis is the most common and powerful way to manually control whitespace. For example, to render a list of items without any spaces between them, you can use the minus sign to remove the newlines and indentation:n

{% for item in seq -%}n    {{ item }}{%- endfor %}

nIf seq is a list of numbers from 1 to 3, the output would be 123. Without the minus signs, the output would include the newlines and indentation from the template, resulting in:n

1n2n3

nThis manual control is invaluable for creating tight, compact output, such as CSV files, JavaScript, or any format that is sensitive to extra whitespace.n

The Plus (+) Sign

nThe plus sign is the opposite of the minus sign; it manually disables the automatic stripping behavior.n

n
• {%+ disables lstrip_blocks for that specific tag.

n

• +%}` disables trim_blocks for that specific tag.

n

nThis is useful in rare cases where you want to keep the whitespace around a specific block even when trim_blocks or lstrip_blocks are globally enabled.nn

---

nn

Other Whitespace Behaviors

n

n
• Trailing Newline: By default, Jinja strips a single trailing newline at the end of a template. To preserve this newline, you can enable the keep_trailing_newline configuration option.

n

• Line Statements: If you enable Jinja’s line statements feature, all leading whitespace on a line is automatically stripped up to the beginning of the line statement.

n

nn

---

nn

Conclusion

nControlling whitespace in Jinja templates is essential for generating clean, predictable output, especially for non-HTML formats. While global configurations like trim_blocks and lstrip_blocks provide a good starting point, the manual control offered by the minus (-) and plus (+) signs gives you the precision needed for specific use cases. By mastering these tools, you can ensure your templates produce exactly the output you intend, without any unexpected blank lines or spaces.nn