Začínáme

# Instalace

djLint je napsaný v Pythonu a publikovaný na PyPI. S uv ho přidejte do projektu jako vývojovou závislost:

uv add --dev djlint

Nebo ho nainstalujte jako samostatný nástroj:

uv tool install djlint

Nebo pomocí pip:

pip install djlint

Nebo pomocí pipx:

pipx install djlint

Nebo v systémech macOS a Linux pomocí formule Homebrew, kterou spravuje komunita:

brew install djlint

Nebo pomocí npm. Upozornění: balíček npm je jen obálka. Jeho instalační skript spustí pip pro ten python3, který je zrovna v systémové cestě, a nainstaluje verzi djLint odpovídající danému vydání npm, což může novější djLint nahradit starším. npm skutečný balíček nespravuje ani neodinstaluje, takže pokud můžete, použijte raději pip.

npm i djlint

Chcete-li djLint spouštět při každém commitu, přečtěte si část pre-commit.

# Použití z příkazového řádku

djLint je aplikace pro příkazový řádek. Pokročilou konfiguraci popisuje stránka Konfigurace.

Usage: djlint [OPTIONS] SRC ...

  djLint · HTML template linter and formatter.

Options:
  --version                       Show the version and exit.
  --lsp                           Run as a language server over stdio, for
                                  editors.
  -e, --extension TEXT            File extension to check [default: html]
  -i, --ignore TEXT               Codes to ignore. ex: "H014,H017"
  --reformat                      Reformat the file(s).
  --check                         Check formatting on the file(s).
  --stdin-filename TEXT           Filename to use for per-file-ignores and
                                  messages when reading from stdin. [default: -]
  --indent INTEGER                Indent spacing. [default: 4]
  --quiet                         Do not print diff when reformatting.
  --profile TEXT                  Enable defaults by template language. ops:
                                  django, jinja, nunjucks, handlebars, liquid,
                                  golang, angular, tera, askama, html [default:
                                  html]
  --require-pragma                Only format or lint files that starts with a
                                  comment with the text 'djlint:on'
  --lint                          Lint for common issues. [default option]
  --use-gitignore                 Use .gitignore file to extend excludes.
  --allow-empty-input             Exit with 0 instead of 2 when the given paths
                                  match no files.
  --warn                          Return errors as warnings.
  --preserve-leading-space        Attempt to preserve leading space on text.
  --preserve-blank-lines          Attempt to preserve blank lines.
  --preserve-class-newlines       Preserve line breaks inside multiline class
                                  attributes.
  --format-css                    Also format contents of <style> tags.
  --format-js                     Also format contents of <script> tags.
  --format-attribute-js-json      Also format JavaScript/JSON inside HTML
                                  attributes.
  --format-attribute-js-json-pattern TEXT
                                  Regex pattern to match JavaScript attributes.
  --format-attribute-js-json-min-props INTEGER
                                  Minimum number of properties to treat
                                  attribute content as JS/JSON.
  --configuration FILE            Path to global configuration file in
                                  djlint.toml, .djlint.toml, or .djlintrc format
  --prefer-configuration          Let --configuration override the project's own
                                  config file, rather than the other way round.
  --rules FILE                    Path to custom rules file in
                                  .djlint_rules.yaml format
  --statistics                    Count the number of occurrences of each
                                  error/warning code.
  --include TEXT                  Codes to include. ex: "H014,H017"
  --ignore-case                   Do not fix case on known html tags.
  --ignore-blocks TEXT            Comma list of template blocks to not indent.
  --blank-line-after-tag TEXT     Add an additional blank line after {% <tag>
                                  ... %} tag groups.
  --blank-line-before-tag TEXT    Add an additional blank line before {% <tag>
                                  ... %} tag groups.
  --line-break-after-multiline-tag
                                  Do not condense the content of multi-line tags
                                  into the line of the last attribute.
  --custom-blocks TEXT            Indent custom template blocks. For example {%
                                  toc %}...{% endtoc %}
  --custom-html TEXT              Indent custom HTML tags. For example <mjml>
  --exclude TEXT                  Override the default exclude paths.
  --extend-exclude TEXT           Add additional paths to the default exclude.
  --linter-output-format TEXT     Customize order of linter output message.
  --max-line-length INTEGER       Max line length. [default: 120]
  --max-attribute-length INTEGER  Max attribute length. [default: 70]
  --format-attribute-template-tags
                                  Attempt to format template syntax inside of
                                  tag attributes.
  --single-attribute-per-line     When an opening tag wraps, put each attribute
                                  on its own line.
  --per-file-ignores <TEXT TEXT>...
                                  Ignore linter rules on a per-file basis.
  --indent-css INTEGER            Set CSS indent level.
  --indent-js INTEGER             Set JS indent level.
  --close-void-tags               Add closing mark on known void tags. Ex: <img>
                                  becomes <img />
  --no-line-after-yaml            Do not add a blank line after yaml front
                                  matter.
  --name-endblocks                Name the endblock of a block written across
                                  lines.
  --sort-attributes               Sort attributes by name, with id first and
                                  class second.
  --sort-load-tags                Sort the libraries in {% load %} tags.
  --no-indent-inner-html          Do not indent <head> and <body> below <html>.
  --no-function-formatting        Do not attempt to format function contents.
  --no-set-formatting             Do not attempt to format set contents.
  --keep-br-inline                Keep <br> on the line of the text it breaks.
  --no-entity-formatting          Do not rewrite entity references as
                                  characters.
  --quote-style [double|single]   Quotes to use for strings inside template
                                  tags. [default: double]
  --max-blank-lines INTEGER       Consolidate blank lines down to x lines.
                                  [default: 0]
  --github-output / --no-github-output
                                  Output GitHub-compatible formatting.
  --sarif                         Output findings as SARIF 2.1.0 json, for
                                  GitHub code scanning and other tools.
  -h, --help                      Show this message and exit.

# Cesta, nebo stdin

djLint pracuje s cestou i se standardním vstupem (stdin).

Spuštění s cestou:

djlint /path/to/templates --lint

Nebo s konkrétním souborem:

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

Nebo se stdin:

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

Stdin lze použít i k přeformátování kódu. Výstupem bude jen naformátovaný kód bez dalších zpráv.

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

Výstup:

<div></div>

Při čtení ze stdin nemá djLint žádnou skutečnou cestu, se kterou by porovnal per-file-ignores nebo kterou by zobrazil ve zprávách, a proto ve výchozím nastavení používá -. Pomocí --stdin-filename sdělíte djLint skutečnou cestu obsahu předaného rourou, například když integrace v editoru při ukládání posílá obsah souboru rourou.

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

# Návratové kódy

Jen kód 1 znamená, že se djLint na vaše šablony podíval a nelíbilo se mu, co našel. Kód 2 vždy znamená, že samotné spuštění nesplnilo svůj účel, takže pipeline může s oběma případy zacházet různě.

Právě kód 2 zachytí spuštění, které nezkontrolovalo vůbec nic: chybnou cestu, --extension, které už neodpovídá, nebo šablony, které se přesunuly. Bez něj by takové spuštění tiše prošlo.

Soubory, které djLint našel a pak záměrně přeskočil kvůli exclude, extend_exclude, use_gitignore nebo require_pragma, nejsou chybou. Takové spuštění skončí s kódem 0, protože konfigurace udělala přesně to, co jí bylo řečeno. Díky tomu také exclude funguje v pre-commit, který předává názvy vašich připravených (staged) souborů bez ohledu na to, zda chcete, aby se na ně djLint díval.

Pokud je pro vaši pipeline normální, že cesta oprávněně neobsahuje žádné šablony, vypněte kód 2 pomocí allow_empty_input:

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