Controlling whitespace in Jinja2 templates

For background perspective, Jinja is used as a templating system by various Python projects like Django, Flask, or Ansible.

From the Jinja2 documentation, there are two options to control whitespace in Jinja templates:

• trim_blocks
• lstrip_blocks

But actually, there's more to it. The "Template Designer Documentation" specifically for whitespace control is inadequate. That's why I wrote this article.

Jinja in Ansible

In Ansible's Template module, you can see in the source code

• trim_blocks defaults to true
• lstrip_blocks defaults to false

But what does this mean? What do these options do? And how do I use them in my Ansible templates?

trim blocks means the first newline after a block is removed (block, not variable tag!)

lstrip blocks means leading spaces and tabs are stripped from the start of a line to a block.

So, I can read words, but without context nor further example and explanation, I can't decode what "from the start of a line to a block" means.

In the task

In at least v2.9 of Ansible, the Template module has options to specify both.

• 2.9 docs for the template module
• latest docs for the template module
  • parameter lstrip_blocks
  • parameter trim_blocks

In the template file

As the very first line of your template file, you can use a magic comment directive to control the behavior of the Ansible Template module #jinja2: trim_blocks: "true", lstrip_blocks: "true"

By hand

I was so frustrated by the lack of clear examples that showed all variants, I created a project on GitHub called test-jinja that does exactly that. (Inspiration from https://github.com/ansible/ansible/pull/37478)

You could also use the jinja2 live parser project to interactively preview jinja.

If you're confused about Variable notation and how those are defined in templates, see https://jinja.palletsprojects.com/en/3.1.x/templates/#variables

Debugging

Just put {% debug %} somewhere in your template file. This didn't work for me in Ansible 2.9

More

Bloomreach Engagement is a commercial Web product that uses Jinja for templating. So they have a pretty good reference guide.

See Also

For whitespace formatting of YAML block scalars, see the yamllint article.== References ==