Context
My colleagues are starting to enhance jinja2 templates that I have developed, and I want my syntax to be as readable and easy for them to navigate as possible. But I don't know how to resolve the challenge that I've reproduced in it's simplest form below:
Minimal reproducible example
When jinja2 syntax is not interspersed within HTML, html parent/child relationships are easy to spot because of the vertical alignment, such as in the example below:
<li>
<p>List Item 1</p>
<p>List Item 2</p>
<p>List Item 3</p>
<p>List Item 4</p>
<p>List Item 5</p>
</li>
And the nested blocks of jinja2 syntax are likewise easy to trace back to their hierarchical precedents in the following example:
{% if foo == bar %}
{% if foo == 1 %}
# Do something
{% endif %}
{% if foo == 2 %}
# Do something
{% endif %}
{% endif %}
But if the two are merged, readability diminishes.
When the indentation of the jinja2 template is given priority, it makes the html parent/child relationships harder to see:
<li>
<p>List Item 1</p>
{% if foo == bar %}
<p>List Item 2</p>
{% if foo == 1 %}
<p>List Item 3</p>
{% endif %}
{% if foo == 2 %}
<p>List Item 4</p>
{% endif %}
{% endif %}
<p>List Item 5</p>
</li>
And if the html indentation is given priority, it makes it harder to trace nested blocks back to their hierarchical precedents:
<li>
<p>List Item 1</p>
{% if foo == bar %}
<p>List Item 2</p>
{% if foo == 1 %}
<p>List Item 3</p>
{% endif %}
{% if foo == 2 %}
<p>List Item 4</p>
{% endif %}
{% endif %}
<p>List Item 5</p>
</li>
I've seen other indentation patterns that split the difference, but they all suffer from lack of readability.
This minimal reproducible example is still fairly easy to visually parse because there is little distance between lines that share a relationship. But the impact is much more onerous when working with large templates.
The Question
Is there an official indentation standard for jinja2 and html that minimizes these tradeoffs? If so, where is the standard discussed?
What I've found so far
I've searched the jinja2 docs for the term "indent" and the two results are not relevant. Some of the Google and Bing results address questions of indentation, but not in this particular context, like these: link, link, link, link, link, link
It seems like this would be a fundamental question, and I apologize if I've overlooked the obvious places where it is answered. Thank you for your help!
