設定

設定可以透過專案的 pyproject.toml 檔案、djlint.toml 或 .djlint.toml 檔案，或是 .djlintrc 檔案進行。命令列引數一律會覆寫設定檔中的任何設定。除非設定了 --prefer-configuration，否則專案層級的設定會覆寫以 --configuration 指定的全域設定檔。

pyproject.toml 的格式為 toml。

[tool.djlint]
<config options>

djlint.toml 和 .djlint.toml 的格式為 toml。

<config options>

.djlintrc 的格式為 json。

{ "option": "value" }

選項

篩選選項

allow_empty_input

始於 1.44.0formatterlinter

當指定的路徑完全沒有比對到任何檔案時，以 0 而不是 2 結束。已找到、但隨後被 exclude、extend_exclude、use_gitignore 或 require_pragma 略過的檔案，本來就會以 0 結束。預設為停用。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

allow_empty_input=true

allow_empty_input=true

"allow_empty_input": true

--allow-empty-input

blank_line_after_tag

始於 0.4.2formatter

在 {% <tag> ... %} 標籤群組之後額外加上一個空白行。空白行永遠不會被加在區塊的結尾。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

blank_line_after_tag="load,extends,include"

blank_line_after_tag="load,extends,include"

"blank_line_after_tag": "load,extends,include"

--blank-line-after-tag "load,extends,include"

blank_line_before_tag

始於 1.8.0formatter

在 {% <tag> ... %} 標籤群組之前額外加上一個空白行。空白行永遠不會被加在檔案或區塊的開頭，也不會加在相似的標籤之間。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

blank_line_before_tag="load,extends,include"

blank_line_before_tag="load,extends,include"

"blank_line_before_tag": "load,extends,include"

--blank-line-before-tag "load,extends,include"

close_void_tags

始於 1.26.0formatterlinter

為已知的空元素標籤加上結尾標記，讓 <img> 變成 <img />。在此選項下，要求相反寫法的 H018 不會被回報。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

close_void_tags=true

close_void_tags=true

"close_void_tags": true

--close-void-tags

custom_blocks

始於 0.3.5formatter

用來縮排自訂的程式碼區塊。例如 {% toc %}...{% endtoc %}。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

custom_blocks="toc,example"

custom_blocks="toc,example"

"custom_blocks": "toc,example"

--custom-blocks "toc,example"

custom_html

始於 0.7.0formatter

用來縮排自訂的 HTML 標籤。例如 <mjml>、<simple-greeting> 或 <mj-\w+>

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

custom_html="mjml,simple-greeting,mj-\\w+"

custom_html="mjml,simple-greeting,mj-\\w+"

"custom_html": "mjml,simple-greeting,mj-\\w+"

--custom-html "mjml,simple-greeting,mj-\\w+"

exclude

始於 0.4.0linterformatter

覆寫預設的排除路徑。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

exclude=".venv,venv,.tox,.eggs,..."

exclude=".venv,venv,.tox,.eggs,..."

"exclude": ".venv,venv,.tox,.eggs,..."

--exclude ".venv,venv,.tox,.eggs,..."

extend_exclude

始於 0.4.0linterformatter

在預設的排除路徑之外新增其他路徑。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

extend_exclude=".custom"

extend_exclude=".custom"

"extend_exclude": ".custom"

--extend-exclude ".custom"

extension

始於 0.0.5linterformatter

用來只尋找具有特定副檔名的檔案。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

extension="html.dj"

extension="html.dj"

"extension": "html.dj"

--extension "html.dj"
# or
-e "html.dj"

files

始於 1.14.0linterformatter

作為 djlint 來源的路徑清單。指定此選項時，命令列的來源必須是 -，就像使用 stdin 一樣。--stdin-filename 會讓 - 無論如何都代表 stdin。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

[tool.djlint]
files=["index.html"]

files=["index.html"]

"files": [
    "index.html"
]

index.html

format_attribute_js_json

始於 1.37.0formatter

格式化 HTML 屬性內的 JavaScript 和 JSON 程式碼。這會格式化 onclick、x-* 及其他與 JavaScript 相關的屬性中的物件常值和 JavaScript 程式碼。屬性數量少於 format_attribute_js_json_min_props 的物件不會被格式化。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

format_attribute_js_json=true

format_attribute_js_json=true

"format_attribute_js_json": true

--format-attribute-js-json

format_attribute_js_json_min_props

始於 1.37.0formatter

JavaScript/JSON 物件要被格式化所需的最少屬性數量。預設值為 2。屬性數量較少的物件會保持在同一行。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

format_attribute_js_json_min_props=3

format_attribute_js_json_min_props=3

"format_attribute_js_json_min_props": 3

--format-attribute-js-json-min-props 3

format_attribute_js_json_pattern

始於 1.37.0formatter

用來比對要格式化之 JavaScript 屬性的自訂 regex 模式。預設模式會比對常見的 JavaScript 屬性，例如 onclick、x-*、Vue.js 指令、Alpine.js 指令、Angular 指令等。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

format_attribute_js_json_pattern="^(on[a-z]+|data-[a-z-]+|x-[a-z-]+)$"

format_attribute_js_json_pattern="^(on[a-z]+|data-[a-z-]+|x-[a-z-]+)$"

"format_attribute_js_json_pattern": "^(on[a-z]+|data-[a-z-]+|x-[a-z-]+)$"

--format-attribute-js-json-pattern "^(on[a-z]+|data-[a-z-]+|x-[a-z-]+)$"

format_attribute_template_tags

始於 0.6.7formatter

格式化工具會嘗試格式化標籤屬性內的範本語法。預設為停用。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

format_attribute_template_tags=true

format_attribute_template_tags=true

"format_attribute_template_tags": true

--format-attribute-template-tags

format_css

始於 1.9.0formatter

使用 css-beautify 格式化 style 標籤的內容。所有設定選項請參閱 css-beautify。範本語法並未完全支援。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

[tool.djlint]
format_css=true

[tool.djlint.css]
indent_size=5

format_css=true

[css]
indent_size=5

"format_css": true,
"css": {
        "indent_size": 5
    }

--format-css --indent-css 5

format_js

始於 1.9.0formatter

使用 js-beautify 格式化 script 標籤的內容。所有設定選項請參閱 js-beautify。範本語法並未完全支援。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

[tool.djlint]
format_js=true

[tool.djlint.js]
indent_size=5

format_js=true

[js]
indent_size=5

"format_js": true,
"js": {
        "indent_size": 5
    }

--format-js --indent-js 5

ignore

始於 0.1.5linter

忽略 linter 代碼。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

ignore="H014,H015"

ignore="H014,H015"

"ignore": "H014,H015"

--ignore "H014,H015"

ignore_blocks

始於 1.24.0formatter

用來略過範本標籤子元素的縮排。子元素會被當成同層元素，並依此縮排。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

ignore_blocks="raw,example"

ignore_blocks="raw,example"

"ignore_blocks": "raw,example"

--ignore-blocks "raw,example"

ignore_case

始於 1.23.0formatterlinter

不要嘗試修正已知 html 標籤的大小寫。在此選項下，H009 和 H010 不會被回報。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

[tool.djlint]
ignore_case=true

ignore_case=true

"ignore_case": true

--ignore-case

include

始於 1.20.0linter

納入 linter 代碼。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

include="H014,H015"

include="H014,H015"

"include": "H014,H015"

--include "H014,H015"

indent

始於 0.3.5formatter

用來變更程式碼的縮排。預設值為 4（四個空格），或專案根目錄中 .editorconfig 的 indent_size。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

indent=3

indent=3

"indent": 3

--indent 3

keep_br_inline

始於 1.45.0formatter

讓 <br> 留在它所斷開的文字那一行，而不是讓它獨佔一行。渲染為前面內容下方一條橫線的 <hr> 不受影響。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

keep_br_inline=true

keep_br_inline=true

"keep_br_inline": true

--keep-br-inline

line_break_after_multiline_tag

始於 1.27.0formatter

不要將多行標籤的內容壓縮到最後一個屬性所在的那一行。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

line_break_after_multiline_tag=true

line_break_after_multiline_tag=true

"line_break_after_multiline_tag": true

--line-break-after-multiline-tag

linter_output_format

始於 0.6.7linter

自訂輸出訊息的順序。預設值=“{code} {line} {message} {match}”。如果訊息中不包含 {filename}，輸出就會依檔案分組，並自動為每個群組加上標頭。

可用的變數：

{filename}
{line}
{end}
{code}
{message}
{match}

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

linter_output_format="{filename}:{line}: {code} {message} {match}"

linter_output_format="{filename}:{line}: {code} {message} {match}"

"linter_output_format": "{filename}:{line}: {code} {message} {match}"

--linter-output-format "{filename}:{line}: {code} {message} {match}"

max_attribute_length

始於 0.5.8formatter

如果屬性長度超過這個值，格式化工具會嘗試將標籤屬性換行。預設值為 70。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

max_attribute_length=10

max_attribute_length=10

"max_attribute_length": 10

--max-attribute-length 10

max_blank_lines

始於 1.31.0formatter

將連續的空白行合併為最多 x 行。預設值為 0，表示會移除空白行。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

max_blank_lines=5

max_blank_lines=5

"max_blank_lines": 5

--max-blank-lines 5

max_line_length

始於 0.5.7formatter

如果行長度不會超過這個值，格式化工具會嘗試將部分 html 和範本標籤放在同一行，而不是換行。預設值為 120，或專案根目錄中 .editorconfig 的 max_line_length。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

max_line_length=120

max_line_length=120

"max_line_length": 120

--max-line-length 120

name_endblocks

始於 1.45.0formatter

對於跨越多行撰寫的區塊，將區塊的名稱寫入關閉它的 {% endblock %}。這正是 T003 所要求的。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

name_endblocks=true

name_endblocks=true

"name_endblocks": true

--name-endblocks

no_entity_formatting

始於 1.45.0formatter

不要將字元實體參照改寫為它所代表的字元，因此 © 會保持原樣，而不會變成 ©。帶有語法作用的實體以及不可見字元的實體，無論如何都不會被改寫。在此選項下 H023 仍會回報實體；若要保留實體，請將 H023 加入 ignore。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

no_entity_formatting=true

no_entity_formatting=true

"no_entity_formatting": true

--no-entity-formatting

no_function_formatting

始於 1.30.2formatter

不要嘗試格式化 {{ }} 運算式內函式呼叫的引數。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

no_function_formatting=true

no_function_formatting=true

"no_function_formatting": true

--no-function-formatting

no_indent_inner_html

始於 1.45.0formatter

不要將 <head> 和 <body> 縮排在 <html> 之下，這是 VS Code 預設的 html 格式化工具排版文件的方式。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

no_indent_inner_html=true

no_indent_inner_html=true

"no_indent_inner_html": true

--no-indent-inner-html

no_line_after_yaml

始於 1.29.0formatter

不要在 yaml front matter 之後加上空白行。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

no_line_after_yaml=true

no_line_after_yaml=true

"no_line_after_yaml": true

--no-line-after-yaml

no_set_formatting

始於 1.30.2formatter

不要嘗試格式化 {% set %} 標籤的內容。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

no_set_formatting=true

no_set_formatting=true

"no_set_formatting": true

--no-set-formatting

per_file_ignores

始於 1.7.0linter

針對個別檔案忽略 linter 規則。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

[tool.djlint.per-file-ignores]
"file.html"= "H026,H025"
"file_two.html"="H001"

[per-file-ignores]
"file.html"= "H026,H025"
"file_two.html"="H001"

"per-file-ignores": {
        "file.html": "H026,H025",
        "file_two.html":"H001"
    }

--per-file-ignores "file.html" "H026,H025" --per-file-ignores "file_two.html" "H001"

prefer_configuration

始於 1.45.0formatterlinter

讓 configuration 所指定的檔案覆寫專案本身的設定檔。configuration 指定的是全域檔案，因此預設情況下，當兩者設定了相同的項目時，以範本旁的 pyproject.toml 或 .djlintrc 為準。僅限命令列使用，因為它決定的是設定檔本身如何被讀取。

--prefer-configuration

preserve_blank_lines

始於 1.3.0formatter

盡可能保留空白行。適合空白行是刻意為之的非 html 範本檔案。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

preserve_blank_lines=true

preserve_blank_lines=true

"preserve_blank_lines": true

--preserve-blank-lines

preserve_class_newlines

始於 1.39.0formatter

保留多行 class 屬性內的換行。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

preserve_class_newlines=true

preserve_class_newlines=true

"preserve_class_newlines": true

--preserve-class-newlines

preserve_leading_space

始於 1.2.0formatter

盡可能保留文字開頭的空白。適合文字縮排是刻意為之的非 html 範本檔案。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

preserve_leading_space=true

preserve_leading_space=true

"preserve_leading_space": true

--preserve-leading-space

profile

始於 0.4.5linterformatter

為範本語言設定 profile。profile 會啟用適用於你的範本語言的 linter 規則，也可能改變重新格式化的方式。例如在 handlebars 中，{{#if}} 標籤內不會有空格。

選項：

html（預設值）
django
jinja
nunjucks（用於 nunjucks 和 twig）
handlebars（用於 handlebars 和 mustache）
liquid（shopify、jekyll、eleventy）
golang（go 範本；hugo、helm）
angular
tera（也適用於 zola；minijinja 請使用 jinja）
askama（rust 中的 jinja 風格範本；rust 運算式永遠不會被重新格式化）

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

profile="django"

profile="django"

"profile": "django"

--profile "django"

quiet

始於 0.0.9formatterlinter

重新格式化時不要印出 diff。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

quiet=true

quiet=true

"quiet": true

--quiet

quote_style

始於 1.45.0formatterlinter

範本標籤內字串所使用的引號，可以是 double（預設值）或 single。T002 會要求使用相同的引號。格式化工具在條件判斷中也會使用它們，例如 {% if x == "a" %}，因此同一個檔案不會以兩種寫法拼寫同一個字串。HTML 屬性的引號則交由 H008 處理。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

quote_style="single"

quote_style="single"

"quote_style": "single"

--quote-style single

require_pragma

始於 0.5.8formatter

只格式化或 lint 以一個僅含 ‘djlint:on’ 文字的註解開頭的檔案。這個註解可以是 HTML 註解，或是 profile 設定所定義之範本語言的註解。如果沒有指定 profile，則接受任何一種範本語言的註解。

<!-- djlint:on -->
{# djlint:on #}
{% comment %} djlint:on {% endcomment %}
{{ /* djlint:on */ }}
{{!-- djlint:on --}}

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

require_pragma=true

require_pragma=true

"require_pragma": true

--require-pragma

single_attribute_per_line

始於 1.40.0formatter

開始標籤需要換行時，將標籤名稱、每個屬性和結尾的角括號分別放在各自的行上。預設為停用。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

single_attribute_per_line=true

single_attribute_per_line=true

"single_attribute_per_line": true

--single-attribute-per-line

sort_attributes

始於 1.45.0formatter

依名稱排序屬性，id 排第一，class 排第二。若標籤的屬性受範本標籤控制，則會保留原本的撰寫順序，因為將屬性移出它所在的分支會改變頁面。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

sort_attributes=true

sort_attributes=true

"sort_attributes": true

--sort-attributes

sort_load_tags

始於 1.47.0formatter

排序 django {% load %} 標籤中的函式庫，並移除重複寫了兩次的函式庫，因此 {% load static i18n %} 會變成 {% load i18n static %}。在 {% load a b from library %} 中，會排序 from 之前的名稱。當兩個函式庫定義了同名的標籤或篩選器時，以最後載入的為準，因此排序可能會改變範本所使用的是哪一個。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

sort_load_tags=true

sort_load_tags=true

"sort_load_tags": true

--sort-load-tags

stdin_filename

始於 1.43.0formatterlinter

從 stdin 讀取時，用於 per-file-ignores 和訊息的檔案名稱。預設為 “-”。

--stdin-filename templates/index.html

use_gitignore

始於 0.5.9linterformatter

將 .gitignore 的排除項目加入預設的排除路徑。預設為停用。

pyproject.toml
djlint.toml / .djlint.toml
.djlintrc
cli

use_gitignore=true

use_gitignore=true

"use_gitignore": true

--use-gitignore

version

始於 0.3.9formatterlinter

顯示版本並結束。

--version

warn

始於 0.7.6formatterlinter

將錯誤以警告的形式傳回。

--warn

找不到任何結果，請試試其他搜尋。

設定

# 選項

# allow_empty_input

# blank_line_after_tag

# blank_line_before_tag

# close_void_tags

# custom_blocks

# custom_html

# exclude

# extend_exclude

# extension

# files

# format_attribute_js_json

# format_attribute_js_json_min_props

# format_attribute_js_json_pattern

# format_attribute_template_tags

# format_css

# format_js

# ignore

# ignore_blocks

# ignore_case

# include

# indent

# keep_br_inline

# line_break_after_multiline_tag

# linter_output_format

# max_attribute_length

# max_blank_lines

# max_line_length

# name_endblocks

# no_entity_formatting

# no_function_formatting

# no_indent_inner_html

# no_line_after_yaml

# no_set_formatting

# per_file_ignores

# prefer_configuration

# preserve_blank_lines

# preserve_class_newlines

# preserve_leading_space

# profile

# quiet

# quote_style

# require_pragma

# single_attribute_per_line

# sort_attributes

# sort_load_tags

# stdin_filename

# use_gitignore

# version

# warn

選項

allow_empty_input

blank_line_after_tag

blank_line_before_tag

close_void_tags

custom_blocks

custom_html

exclude

extend_exclude

extension

files

format_attribute_js_json

format_attribute_js_json_min_props

format_attribute_js_json_pattern

format_attribute_template_tags

format_css

format_js

ignore

ignore_blocks

ignore_case

include

indent

keep_br_inline

line_break_after_multiline_tag

linter_output_format

max_attribute_length

max_blank_lines

max_line_length

name_endblocks

no_entity_formatting

no_function_formatting

no_indent_inner_html

no_line_after_yaml

no_set_formatting

per_file_ignores

prefer_configuration

preserve_blank_lines

preserve_class_newlines

preserve_leading_space

profile

quiet

quote_style

require_pragma

single_attribute_per_line

sort_attributes

sort_load_tags

stdin_filename

use_gitignore

version

warn