시작하기

# 설치

djLint는 Python으로 만들어졌으며 PyPI에 게시되어 있습니다. uv를 사용한다면 프로젝트에 개발 의존성으로 추가합니다.

uv add --dev djlint

또는 독립 실행형 도구로 설치합니다.

uv tool install djlint

또는 pip으로 설치합니다.

pip install djlint

또는 pipx로 설치합니다.

pipx install djlint

또는 macOS나 Linux에서는 커뮤니티가 관리하는 Homebrew 포뮬러로 설치합니다.

brew install djlint

또는 npm으로 설치합니다. 경고: npm 패키지는 래퍼일 뿐입니다. 설치 스크립트는 시스템 경로에 있는 python3이 무엇이든 그것으로 pip을 실행해 해당 npm 릴리스에 맞는 djLint 버전을 설치하므로, 더 새로운 djLint가 이전 버전으로 바뀔 수 있습니다. npm은 실제 패키지를 관리하거나 제거하지 않으므로 가능하면 pip을 사용하세요.

npm i djlint

커밋할 때마다 djLint를 실행하려면 pre-commit을 참고하세요.

# CLI 사용법

djLint는 명령줄 애플리케이션입니다. 고급 구성은 구성 페이지를 참고하세요.

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.

# 경로와 stdin 사용

djLint는 경로나 stdin으로 입력을 받습니다.

경로를 지정해 실행하는 경우:

djlint /path/to/templates --lint

특정 파일을 지정하는 경우:

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

stdin을 사용하는 경우:

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

stdin으로 코드를 다시 포맷할 수도 있습니다. 이때는 메시지 없이 포맷된 코드만 출력합니다.

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

출력:

<div></div>

stdin에서 읽을 때는 per-file-ignores와 대조하거나 메시지에 표시할 실제 경로가 없으므로, djLint는 기본값으로 -를 사용합니다. 예를 들어 에디터 통합이 저장할 때 파일 내용을 파이프로 넘기는 경우처럼, 파이프로 넘긴 내용의 실제 경로를 djLint에 알려 주려면 --stdin-filename을 전달하세요.

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

# 종료 코드

코드 1만이 djLint가 템플릿을 살펴보고 마음에 들지 않는 점을 발견했다는 뜻입니다. 코드 2는 언제나 실행 자체가 제 역할을 하지 못했다는 뜻이므로, 파이프라인에서 두 경우를 다르게 처리할 수 있습니다.

코드 2는 아무것도 검사하지 않은 실행을 잡아냅니다. 경로가 잘못되었거나, --extension이 더 이상 일치하지 않거나, 템플릿이 다른 곳으로 옮겨진 경우입니다. 이 코드가 없다면 그런 실행은 조용히 통과합니다.

djLint가 찾기는 했지만 exclude, extend_exclude, use_gitignore, require_pragma에 따라 의도적으로 건너뛴 파일은 오류가 아닙니다. 구성이 지시받은 대로 정확히 동작했으므로 그 실행은 0으로 종료합니다. 덕분에 pre-commit에서도 exclude가 동작합니다. pre-commit은 djLint가 살펴보기를 원하든 원하지 않든 스테이징된 파일의 이름을 넘기기 때문입니다.

템플릿이 없는 것이 정상인 경로를 파이프라인에서 다룬다면 allow_empty_input으로 코드 2를 끄세요.

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