Opened 10 years ago

Last modified 16 months ago

#14831 new New feature

Django Template Style Guide

Reported by: Simon Meers Owned by: nobody
Component: Documentation Version: 1.2
Severity: Normal Keywords: template, style, format
Cc: Tobias Kunze Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


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.

Regardless of what is decided, it would be great to have at least some guidelines for templates added to

Change History (6)

comment:1 Changed 10 years ago by Gabriel Hurley

Triage Stage: UnreviewedAccepted

I'm in favor of standards in general. What will probably bring this issue to a consensus most quickly would be the following:

  1. An overview of the various styles found in the current templates,
  2. A draft patch based on whatever the most common/best practice seems to be,
  3. A thread on Django Developers to let folks debate the options.

A few points that should be specified in a style guide for templates:

  • Indentation: how many spaces?
  • Placement of extends and load tags (at the top seems pretty standard).
  • Whether HTML inside a block should always be on its own line or if short blocks should be kept on one line. See the admin base_site template for examples of both.
  • Whether all code inside a block should be indented. (commonly the answer seems to be "no")

There are probably others, but this is what springs to mind so far.

Just to toss my two cents into the ring (how's that for a mixed metaphor?), here's what I think:

Even though there's no guiding document like PEP 8 for HTML, I think applying as much of PEP 8 as makes sense is going to be the simplest answer. It's an established and understood document that Python developers are accustomed to. A couple of items that would tend to apply:

  • Where whitespace will not affect rendered output, break up nested tags onto their own lines to keep from running over 80 characters.
  • Separate blocks (or other discrete groups of tags or logical sections) by blank lines.
  • Imports (i.e. load and extends) should be at the top of the file, on separate lines.
  • Proper whitespace within HTML tags. (<span class="timestamp hidden"> not <span class = " timestamp hidden" >)

I think overall readability and proper indentation of each individual template file is more important than what the HTML output looks like. I wrap my base templates with the spaceless tag though, so it matters less to me.

Use 4 spaces for indentation. (I know 2 spaces is popular for HTML among many developers, but PEP 8 recommends 4 and changing to 2 for templates doesn't offer any substantive improvement while it decreases the visual separation).

comment:2 Changed 10 years ago by ramen

I would like to see such a standards guide as well, especially regarding indentation. In addition to whether all code inside a block should be indented, there seems to be a variety of approaches to indentation around other template tags such as conditionals and loops. My preference would be to indent inside of all template tags that span multiple lines.

comment:3 Changed 9 years ago by anonymous

Severity: Normal
Type: New feature

comment:4 Changed 9 years ago by Simon Meers

Easy pickings: unset
UI/UX: unset

I think much of Gabriel's suggestions here make good sense. Though:

  • I think {% load A B C %} is OK; loading in templates is simpler than importing in python since there are no relative imports, from x import y, etc.
  • I think 4-spaces is too much; in python, nesting can (and should) be avoided; in HTML, deep nesting is unavoidable. I'd therefore advocate 2-space indentation or tabs (the width of which can be configured by your editor)

I personally also indent template tags and HTML tags alike; e.g.

    {% for x in y %}
      <li>{{ x }}</li>
    {% endfor %}

(though this obviously doesn't produce terribly pretty HTML, if anyone cares. I prefer pretty templates.)

This is dangerous bikeshedding territory, but it seems sensible to have a standard within core code, and would also allow the production of django-template emacs modes, TextMate bundles, etc.

comment:5 Changed 9 years ago by Simon Meers

Actually you can use "from" syntax in the load tag, can't you; in those cases it certainly makes sense to keep them on separate lines. Though perhaps that isn't what Gabriel was advocating in the first place; on re-reading he may have been simply saying it shouldn't be on the same line as {% extends %} (which of course must be at the top).

comment:6 Changed 16 months ago by Tobias Kunze

Cc: Tobias Kunze added

By now, there is a place to add further template style guides (currently it only says to add one space between {{ and the variable name. So we'd need a consensus on what a good template style would mean: Indented for template readability or for meaningful HTML indentation? Indented by two spaces or four?

I'd be all for two spaces and indentation as proposed by Simon.

Note: See TracTickets for help on using tickets.
Back to Top