Prise en main

Installation

djLint est écrit en Python et publié sur PyPI. Avec uv, ajoutez-le à votre projet comme dépendance de développement :

uv add --dev djlint

Ou installez-le comme outil autonome :

uv tool install djlint

Ou avec pip :

pip install djlint

Ou avec pipx :

pipx install djlint

Ou avec la formule Homebrew maintenue par la communauté, sous macOS ou Linux :

brew install djlint

Ou avec npm. Attention : le paquet npm n’est qu’une surcouche. Son script d’installation exĂ©cute pip avec le python3 prĂ©sent dans le PATH de votre systĂšme et installe la version de djLint de cette release npm, ce qui peut remplacer un djLint plus rĂ©cent par un plus ancien. npm ne gĂšre ni ne dĂ©sinstalle le vrai paquet : prĂ©fĂ©rez donc pip quand vous le pouvez.

npm i djlint

Pour exécuter djLint à chaque commit, consultez pre-commit.

Utilisation en ligne de commande

djLint est une application en ligne de commande. Consultez la page configuration pour une configuration avancée.

Usage: djlint [OPTIONS] SRC ...

  djLint · HTML template linter and formatter.

Modes:
  --lint                          Lint the files. This is the default when
                                  neither --reformat nor --check is given.
  --reformat                      Format the files in place.
  --check                         Show what formatting would change, without
                                  changing the files.
  --lsp                           Run as a language server over stdio, for
                                  editors.

Files:
  -e, --extension EXT             Extension of the files to look for in folders.
                                  [default: html]
  --exclude PATHS                 Paths to skip, comma-separated, in place of
                                  the default list.
  --extend-exclude PATHS          Paths to skip on top of the default list,
                                  comma-separated.
  --use-gitignore                 Also skip the paths that .gitignore lists.
  --require-pragma                Only format or lint files whose first line is
                                  a djlint:on comment.
  --stdin-filename PATH           Path that stands for stdin in messages,
                                  excludes and per-file ignores. [default: -]
  --allow-empty-input             Exit with 0 instead of 2 when the given paths
                                  match no files.

Configuration:
  --profile NAME                  Template language: html, django, jinja,
                                  nunjucks, handlebars, liquid, golang, angular,
                                  tera, askama, mako or all. It decides which
                                  linter rules run and how template syntax is
                                  formatted. Without one, formatting follows all
                                  and linting follows html.
  --configuration FILE            Global config file: a pyproject.toml,
                                  djlint.toml or .djlintrc. The project's own
                                  config file wins where both set an option.
  --prefer-configuration          Let the --configuration file win over the
                                  project's own config file.

Linter:
  -i, --ignore CODES              Linter codes to skip, comma-separated, for
                                  example H014,H017.
  --include CODES                 Linter codes to turn on, comma-separated, for
                                  example H017. Works for rules that are off by
                                  default and for rules the profile leaves out.
  --per-file-ignores <PATTERN CODES>...
                                  Skip linter codes in the files whose path
                                  matches a regex. Can be repeated.
  --rules FILE                    Custom linter rules, in the .djlint_rules.yaml
                                  format.

Output:
  --quiet                         Do not print diffs, the progress bar or the
                                  summary.
  --warn                          Exit with 0 instead of 1 when there are lint
                                  errors or files to reformat.
  --statistics                    After linting, print how many times each code
                                  was found.
  --linter-output-format FORMAT   Layout of each lint message, from {filename},
                                  {line}, {end}, {code}, {message} and {match}.
                                  [default: {code} {line} {message} {match}]
  --github-output / --no-github-output
                                  Print results as GitHub Actions annotations.
                                  On by default inside GitHub Actions.
  --sarif                         Print findings as a SARIF 2.1.0 JSON document,
                                  for GitHub code scanning and other tools.

Layout:
  --indent N                      Spaces per indent level. [default: 4, or
                                  indent_size from .editorconfig]
  --max-line-length N             Join tags onto one line only when the line
                                  fits within this length. [default: 120, or
                                  max_line_length from .editorconfig]
  --max-attribute-length N        Spread a tag's attributes over lines once they
                                  are longer than this. [default: 70]
  --single-attribute-per-line     When an opening tag wraps, put each attribute
                                  on its own line.
  --line-break-after-multiline-tag
                                  When a tag's attributes are spread over lines,
                                  start its content on a new line.
  --no-indent-inner-html          Do not indent <head> and <body> inside <html>.
  --keep-br-inline                Keep <br> on the line of the text it breaks.
  --custom-blocks TAGS            Names of the custom template blocks to indent,
                                  comma-separated, for example toc.
  --custom-html TAGS              Names of the custom HTML tags to indent,
                                  comma-separated, for example mjml.
  --ignore-blocks TAGS            Template blocks that do not indent their
                                  contents, comma-separated.
  --blank-line-after-tag TAGS     Template tags to follow with a blank line,
                                  comma-separated, for example load,extends.
  --blank-line-before-tag TAGS    Template tags to precede with a blank line,
                                  comma-separated, for example load,extends.
  --max-blank-lines N             Keep at most this many blank lines in a row.
                                  Has no effect with --preserve-blank-lines.
                                  [default: 0]
  --preserve-blank-lines          Keep blank lines where possible.
  --preserve-leading-space        Keep the leading spaces of text lines where
                                  possible.
  --no-line-after-yaml            Do not add a blank line after YAML front
                                  matter.

Rewrites:
  --close-void-tags               Close void tags with a slash, so <img> becomes
                                  <img />.
  --ignore-case                   Do not fix the case of known HTML tags.
  --sort-attributes               Sort attributes by name, with id first and
                                  class second.
  --sort-load-tags                Sort the libraries in {% load %} tags and drop
                                  repeated ones.
  --name-endblocks                Name the block in its {% endblock %} when the
                                  block spans lines.
  --quote-style [double|single]   Quotes for strings inside template tags.
                                  [default: double]
  --no-entity-formatting          Do not rewrite entity references such as
                                  &copy; as the characters they name.
  --no-function-formatting        Do not format the arguments of function calls
                                  inside {{ }}.
  --no-set-formatting             Do not format the contents of {% set %} tags.
  --preserve-class-newlines       Keep the line breaks in class attributes
                                  written across lines.
  --format-attribute-template-tags
                                  Format template syntax inside tag attributes.

CSS and JavaScript:
  --format-css                    Also format the contents of <style> tags, with
                                  css-beautify.
  --indent-css N                  Indent width inside <style> tags, for
                                  --format-css. [default: 4]
  --format-js                     Also format JavaScript and JSON in <script>
                                  tags, with js-beautify.
  --indent-js N                   Indent width inside <script> tags, for
                                  --format-js. [default: 4]
  --format-attribute-js-json      Also format JavaScript and JSON in attributes
                                  such as onclick and x-data.
  --format-attribute-js-json-pattern REGEX
                                  Regex for the names of the attributes to
                                  format as JavaScript or JSON. [default: on*
                                  event handlers and Alpine, Vue, Angular and
                                  Aurelia bindings]
  --format-attribute-js-json-min-props N
                                  Format an object only when it has at least
                                  this many properties. [default: 2]

Other:
  --version                       Show the version and exit.
  -h, --help                      Show this message and exit.

Remarque

Si la commande djlint est introuvable, vérifiez que Python est bien dans votre PATH.

Chemin ou stdin

djLint accepte un chemin ou l’entrĂ©e standard (stdin).

Avec un chemin :

djlint /path/to/templates --lint

Ou un fichier précis :

djlint /path/to/this.mustache --lint

Ou avec stdin :

echo "<div></div>" | djlint -

L’entrĂ©e standard permet aussi de reformater du code. La sortie ne contient alors que le code formatĂ©, sans aucun message.

echo "<div></div>" | djlint - --reformat

Sortie :

<div></div>

Quand il lit l’entrĂ©e standard, djLint n’a pas de vrai chemin Ă  comparer Ă  per-file-ignores ni Ă  afficher dans les messages : il utilise donc - par dĂ©faut. Passez --stdin-filename pour indiquer Ă  djLint le vrai chemin du contenu reçu, par exemple quand une intĂ©gration d’éditeur lui transmet le contenu d’un fichier Ă  l’enregistrement.

echo "<div></div>" | djlint - --stdin-filename templates/index.html

Codes de sortie

Code Signification
0 Tout ce que djLint devait vérifier est correct, ou chaque fichier trouvé a été ignoré par votre configuration.
1 djLint a trouvé des erreurs de linting, ou des fichiers à reformater. Avec --warn, ils sont signalés comme des avertissements et le code de sortie est 0.
2 djLint n’a pas vĂ©rifiĂ© ce que vous lui avez demandé : les chemins ne correspondent Ă  aucun fichier, la ligne de commande ou la configuration est invalide, ou djLint a Ă©chouĂ©.

Seul le code 1 signifie que djLint a examinĂ© vos templates et n’a pas aimĂ© ce qu’il y a trouvĂ©. Le code 2 signifie toujours que l’exĂ©cution elle-mĂȘme n’a pas abouti : un pipeline peut donc traiter les deux cas diffĂ©remment.

C’est le code 2 qui repĂšre une exĂ©cution qui n’a rien vĂ©rifiĂ© du tout : un chemin erronĂ©, une --extension qui ne correspond plus, ou des templates qui ont Ă©tĂ© dĂ©placĂ©s. Sans lui, une telle exĂ©cution passe en silence.

Les fichiers que djLint a bien trouvĂ©s puis volontairement ignorĂ©s, via exclude, extend_exclude, use_gitignore ou require_pragma, ne constituent pas une erreur. L’exĂ©cution se termine alors avec 0, car la configuration a fait exactement ce qu’on lui demandait. C’est aussi ce qui permet Ă  exclude de fonctionner avec pre-commit, qui transmet les noms de vos fichiers indexĂ©s, que vous vouliez ou non que djLint les examine.

Si, dans votre pipeline, il est normal qu’un chemin ne contienne lĂ©gitimement aucun template, dĂ©sactivez le code 2 avec allow_empty_input :

djlint /path/to/templates --lint --allow-empty-input