It would be nice to have a standard template style that should be followed. For example, I like to indent my Django templates by two additional spaces every time I enter a new HTML or template block. The Django core templates vary greatly in regards to style and indentation. Much of the time template readability is sacrificed in favour of attempting to preserve the “appearance” of the generated HTML code.
An overview of the various styles found in the current templates,
A draft patch based on whatever the most common/best practice seems to be,
A thread on the Django Forum to let folks debate the options.
I’ve not done anything (yet) for point (2) above, but I have reviewed the various styles that seem to be in place (1) and am now posting here to let folks debate the options (3)
My findings are (and can be found in more detail in comments 10 through 17:
The usage of {{ is generally followed by a single space (inline javascript seems to be the exception)
The usage of {% is always followed by a single space (the one exception I was able to find was related to a jinja2 whitespace control in ./forms/jinja2/django/forms/widgets/multiwidget.html
{% extends %}is always at the top of html files
{% load %} is nearly always at the top. There are two exceptions.
{% block %}
The following ‘standards’ are used:
- the <link ...> tends to be on a single line, see for example /django/contrib/admin/templates/admin/base.htmlLine 6
- Simple logic for html element classes tends to be on a single line, see for example ./docs/_theme/djangodocs/layout.htmlLine 80
- Single elements can are on a single line, see for example ./django/contrib/admin/templates/admin/base.htmlLine 102
There are two files which may fall outside of the standard:
Thank you for picking this up Ryan—great research and writeup. I am excited for a template style guide that projects could adopt. I’d love to work on a formatted tool to match the guide. (I’d also hope to make it auto-upgrade templates, subsuming ideas listed in long-open django-upgrade issues).
The currently proposed standard matches most of my preferences.
To be explicit, you should also list:
}} is always preceded by a single space
%} is always preceded by a single space
The {% load %} rule description is maybe missing the word “follows”? Like “{% load %} follows and there…”.
Maybe we should allow comments above {% extends %}, since they can be used like a docstring to describe a template’s purpose.
My one preference opposed to the proposal is with {% load %}. I prefer multiple alphabetically sorted {% load %} tags. This style leads to fewer merge conflicts and keeps git blame accurate. I similarly prefer one-import-per-line in Python code and have seen fewer conflicts since adopting this style.
On {% block %}, perhaps we could require {% endblock %} to repeat the block name if not on the same line? This can make longer templates more navigable - “okay, I’ve reached the end of the navigation now…”.
I think I broadly agree with Adam’s suggestions here but I more wanted to post that I’d be very happy to see this.
I also wish there was a good formatter available so people - especially reviewers - don’t have to think about this. I’ve tried a couple and do use one at work but they can often cause very weird looking stuff and excessively long lines. I would certainly argue for one if there was one I thought was good enough… for anyone out there looking for an interesting project
I’ve been fairly happy with djhtml, fwiw. It’s not black levels of “there is only one correct way to format a file”, but it’s consistent and I vastly prefer using it to not using it. I’m guessing it’d be not opinionated enough/not black-like enough for some people, but at least it understands DTL syntax, rather than using a Jinja2 formatter and hoping for the best …
