Djade
A Django template formatter.
You can have any colour you like, as long as it's [d]jade.
Djade formats Django template syntax with a style based on the template style guide in Django's documentation. It does not format HTML or other templated languages.
Djade is fast because it is built in Rust: benchmarked taking 20ms to format 377 templates.
Read more in the introductory post, or below.
Improve your Django and Git skills with my books.
Installation
Use pip:
python -m pip install djade
Python 3.9 to 3.13 supported.
pre-commit hook
You can also install Djade as a pre-commit hook.
First, add the following to the repos
section of your
.pre-commit-config.yaml
file
(docs):
- repo: https://github.com/adamchainz/djade-pre-commit
rev: "" # Replace with the latest tag on GitHub
hooks:
- id: djade
args: [--target-version, "5.1"] # Replace with Django version
The separate repository enables installation without compiling the Rust code.
The default configuration uses pre-commit's files
option__ to pick
up all text files in directories called templates
(source).
You may wish to override this if you have templates in different
directories by adding files
to the hook configuration in your
.pre-commit-config.yaml
file.
Second, format your entire project:
pre-commit run djade --all-files
Check these changes for any potential Djade bugs and commit them. Try
git diff --ignore-all-space
to check non-whitespace changes.
Third, consider adding the previous commit SHA to a
.git-blame-ignore-revs
file__. This will prevent the initial
formatting commit from showing up in git blame
.
Keep the hook installed to continue formatting your templates.
pre-commit's autoupdate
command will upgrade Djade so you can take
advantage of future features.
Usage
djade
is a command line tool that rewrites files in place. Pass a list
of template files to format them:
$ djade --target-version 5.1 templates/engine.html
1 file reformatted
Djade can also upgrade some old template syntax. Add the
--target-version
option with your Django version as <major>.<minor>
to enable applicable fixers:
$ djade --target-version 5.1 templates/engine.html
1 file reformatted
Djade does not have any ability to recurse through directories. Use the
pre-commit integration, globbing, or another technique to apply it to
many files. For example, with git ls-files | xargs
_:
git ls-files -z -- '*.html' | xargs -0 djade
...or PowerShell's ForEach-Object
__:
git ls-files -- '*.html' | %{djade $_}
Options
--target-version
Optional: the version of Django to target, in the format
<major>.<minor>
. If provided, Djade enables its fixers for versions up
to and including the target version. See the list of available versions
with djade --help
.
--check
Avoid writing any formatted files back. Instead, exit with a non-zero status code if any files would have been modified, and zero otherwise.
Formatting
Djade aims to format Django template syntax in a consistent, clean way. It wants to be like Black: opinionated and free of configuration. Djade's style is based on the rules listed in the Django contribution style guide's template style section, plus some more.
Djade does not aim to format the host language of templates (HTML,
etc.). That is a much broader scope and hard to do without semantic
changes. For example, whitespace is significant in some HTML contexts,
such as in <pre>
tags, so even adjusting indentation can affect the
meaning.
Below are the rules that Djade implements.
Rules from the Django style guide:
-
Single spaces at the start and end of variables and tags:
``` diff -{{train}} +{{ train }}
-{% blow whistle %} +{% blow whistle %} ```
-
Label
{% endblock %}
tags that aren't on the same line as their opening{% block %}
tag:diff {% block funnel %} ... -{% endblock %} +{% endblock funnel %}
-
Sort libraries in
{% load %}
tags:diff -{% load coal boiler %} +{% load boiler coal %}
-
Inside variables, no spaces around filters:
diff -{{ fire | stoke }} +{{ fire|stoke }}
-
Inside tags, single spaces between tokens:
diff -{% if locomotive == 'steam engine' %} +{% if locomotive == 'steam engine' %}
-
Unindent top-level
{% block %}
and{% endblock %}
tags when{% extends %}
is used:``` diff - {% extends 'engine.html' %} +{% extends 'engine.html' %}
- {% block boiler %} +{% block boiler %} ...
- {% endblock boiler %} +{% endblock boiler %} ```
Extra rules:
-
No leading empty lines:
``` diff
{% extends 'engine.html' %} ... ```
-
No trailing empty lines:
diff ... {% endblock wheels %} - -
-
Single spaces at the start and end of comments:
diff -{#choo choo#} +{# choo choo #}
-
No labels in
{% endblock %}
tags on the same line as their opening{% block %}
tag:diff -{% block funnel %}...{% endblock funnel %} +{% block funnel %}...{% endblock %}
-
Merge consecutive
{% load %}
tags:diff -{% load boiler %} - -{% load coal %} +{% load boiler coal %}
-
Sort loaded items in
{% load ... from .. %}
tags:
-{% load steam heat from boiler %}
+{% load heat steam from boiler %}
-
Unindent
{% extends %}
tags:diff - {% extends 'engine.html' %} +{% extends 'engine.html' %}
-
Exactly one blank line between top-level
{% block %}
and{% endblock %}
tags when{% extends %}
is used:
{% extends 'engine.html' %}
-
{% block funnel %}
...
{% endblock funnel %}
+
{% block boiler %}
...
{% endblock boiler %}
Fixers
Djade applies the below fixes based on the target Django version from
--target-version
.
Django 4.2+: length_is
-> length
From the release note:
The
length_is
template filter is deprecated in favor oflength
and the==
operator within an{% if %}
tag.
Djade updates usage of the deprecated filter within if
tags, without
other conditions, appropriately:
-{% if engines|length_is:1 %}
+{% if engines|length == 1 %}
Django 4.1+: empty ID json_script
fixer
From the release note:
The HTML
<script>
elementid
attribute is no longer required when wrapping thejson_script
template filter.
Djade removes the argument where json_script
is passed an empty
string, to avoid emitting id=""
:
-{% tracks|json_script:"" %}
+{% tracks|json_script %}
Django 3.1+: trans
-> translate
, blocktrans
/ endblocktrans
-> blocktranslate
/ endblocktranslate
From the release note:
The renamed
translate
andblocktranslate
template tags are introduced for internationalization in template code. The oldertrans
andblocktrans
template tags aliases continue to work, and will be retained for the foreseeable future.
Djade updates the deprecated tags appropriately:
-{% load blocktrans trans from i18n %}
+{% load blocktranslate translate from i18n %}
-{% trans "Engine colours" %}
+{% translate "Engine colours" %}
-{% blocktrans with colour=engine.colour %}
+{% blocktranslate with colour=engine.colour %}
This engine is {{ colour }}.
-{% endblocktrans %}
+{% endblocktranslate %}
Django 3.1+: ifequal
and ifnotequal
-> if
From the release note:
The
{% ifequal %}
and{% ifnotequal %}
template tags are deprecated in favor of{% if %}
.
Djade updates the deprecated tags appropriately:
-{% ifequal engine.colour 'blue' %}
+{% if engine.colour == 'blue' %}
Thomas!
-{% endifequal %}
+{% endif %}
-{% ifnotequal engine.colour 'blue' %}
+{% if engine.colour != 'blue' %}
Not Thomas.
-{% endifnotequal %}
+{% endif %}
Django 2.1+: admin_static
and staticfiles
-> static
From the release note:
{% load staticfiles %}
and{% load admin_static %}
are deprecated in favor of{% load static %}
, which works the same.
Djade updates {% load %}
tags appropriately:
-{% load staticfiles %}
+{% load static %}
-{% load admin_static %}
+{% load static %}
Django 1.3+: legacy variable assignment syntax
The minimum target Django version is 2.1, so this fixer is always active.
Django 1.3 added support for =
to assign variables in {% with %}
and
{% blocktranslate %}
tags. Prior to this, they only supported the
legacy syntax using the as
keyword, which Django still supports.
Djade rewrites the older as
syntax to the newer =
one:
-{% with engines.count as total %}
+{% with total=engines.count %}
...
{% endwith %}
-{% blocktranslate with engine.colour as colour %}
+{% blocktranslate with colour=engine.colour %}
...
{% endblocktranslate %}