開始使用
安裝
djLint 以 Python 開發，並發布在 PyPI 上。使用 uv 時，將它加入專案作為開發相依套件：
uv add --dev djlint或者將它安裝為獨立工具：
uv tool install djlint或者使用 pip：
pip install djlint或者使用 pipx：
pipx install djlint或者在 macOS 或 Linux 上使用由社群維護的 Homebrew formula：
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.注意
如果找不到 djlint 指令，請確認 Python 已加入你的 PATH。
使用路徑與使用 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 讀取時，djLint 沒有實際路徑可用來比對 per-file-ignores 或顯示在訊息中，因此預設使用 -。傳入 --stdin-filename 可以告訴 djLint 透過管線傳入的內容的實際路徑，例如當編輯器整合在儲存時以管線傳入檔案內容的情況。
echo "<div></div>" | djlint - --stdin-filename templates/index.html結束代碼
| 代碼 | 意義 |
|---|---|
0 |
要求 djLint 檢查的所有內容都沒有問題，或是它找到的每個檔案都被你的設定略過了。 |
1 |
djLint 發現了 lint 錯誤，或有需要重新格式化的檔案。--warn 會將這些回報為警告，改以 0 結束。 |
2 |
djLint 沒有檢查你要求的內容：路徑沒有比對到任何檔案、命令列或設定無效，或是 djLint 執行失敗。 |
只有代碼 1 表示 djLint 檢查了你的範本，而且不滿意它找到的內容。代碼 2 一律表示這次執行本身沒有完成任務，因此管線可以分別處理這兩種情況。
代碼 2 能抓出完全沒有檢查任何東西的執行：路徑錯誤、--extension 已不再相符，或範本已經移動。若沒有它，這樣的執行會默默通過。
djLint 確實找到、但隨後透過 exclude、extend_exclude、use_gitignore 或 require_pragma 刻意略過的檔案，不算是錯誤。這種執行會以 0 結束，因為設定完全照著指示運作。這也讓 exclude 能在 pre-commit 底下正常運作，因為 pre-commit 會傳入你暫存檔案的名稱，不論你是否希望 djLint 檢查它們。
如果你的管線中本來就會有合理地不含任何範本的路徑，請使用 allow_empty_input 關閉代碼 2：
djlint /path/to/templates --lint --allow-empty-input