配置

配置可通过项目的 pyproject.toml 文件、djlint.toml 文件或 .djlintrc 文件来完成。命令行参数优先级大于配置文件的任何配置，本地项目设置优先级大于全局配置文件。

这是 pyproject.toml 的格式，遵循 toml 文件格式。

[tool.djlint]
<config options>

这是 djlint.toml 的格式，遵循 toml 文件格式。

<config options>

这是 .djlintrc 的格式，遵循 json 文件格式。

{ "option": "value" }

∞ 参数

∞ blank_line_after_tag

formatter

在 {% <tag> ... %} 标签组后添加空行。

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

formatter

在 {% <tag> ... %} 标签组前添加空行。（空行不会添加到文件开头或同一个标签之间）

blank_line_before_tag="load,extends,include"
"blank_line_before_tag": "load,extends,include"
--blank-line-before-tag "load,extends,include"

∞ close_void_tags

formatter

关闭空标签。

close_void_tags=true
"close_void_tags": true
--close-void-tags

∞ custom_blocks

formatter

设置自定义代码块的缩进，例如 {% toc %}...{% endtoc %}。

custom_blocks="toc,example"
"custom_blocks": "toc,example"
--custom-blocks "toc,example"

∞ custom_html

formatter

设置自定义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

linterformatter

覆盖默认排除路径。

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

∞ extend_exclude

linterformatter

向默认排除列表中添加额外路径。

extend_exclude=".custom"
"extend_exclude": ".custom"
--extend-exclude ".custom"

∞ extension

linterformatter

仅查找具有特定扩展名的文件。

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

∞ files

linterformatter

定义一个作为 djlint 源的路径列表。当指定该选项时，命令行中的源必须设置为 -，就如同使用标准输入（stdin）一样。

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

"files": [
    "index.html"
]
index.html

∞ format_attribute_js_json

formatter

格式化 HTML 属性中的 JavaScript 和 JSON 代码。这会格式化 onclick、x-* 以及其他 JavaScript 相关属性中的对象字面量和 JavaScript 代码。属性数量少于 format_attribute_js_json_min_props 的对象不会被格式化。

format_attribute_js_json=true
"format_attribute_js_json": true
--format-attribute-js-json

∞ format_attribute_js_json_min_props

formatter

JavaScript/JSON 对象需要被格式化的最少属性数量。默认值为 2。属性数量更少的对象会保持在单行。

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

formatter

用于匹配需要格式化的 JavaScript 属性的自定义正则表达式。默认模式会匹配常见 JavaScript 属性，如 onclick、x-*、Vue.js 指令、Alpine.js 指令、Angular 指令等。

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

formatter

格式化标签参数的语法错误。（默认关闭）

format_attribute_template_tags=true
"format_attribute_template_tags": true
--format-attribute-template-tags

∞ format_css

formatter

使用 css-beautify 格式化 style 标签中的内容。全部配置项请参阅 css-beautify，目前模板语法并未得到完全支持。

[tool.djlint]
format_css=true

[tool.djlint.css]
indent_size=5

"format_css": true
"css": {
        "indent_size": 5
    }
--format-css --indent-css 5

∞ format_js

formatter

使用 js-beautify 格式化 script 标签中的内容。全部配置项请参阅 js-beautify，目前模板语法并未得到完全支持。

[tool.djlint]
format_js=true

[tool.djlint.js]
indent_size=5

"format_js": true
"js": {
        "indent_size": 5
    }
--format-js --indent-js 5

∞ ignore

linter

忽略指定的检查规则代码。

ignore="H014,H015"
"ignore": "H014,H015"
--ignore "H014,H015"

∞ ignore_blocks

formatter

跳过模板标签子元素上的缩进。子元素将被视为同级元素，并相应地进行缩进处理。

ignore_blocks="raw,example"
"ignore_blocks": "raw,example"
--ignore-blocks "raw,example"

∞ ignore_case

formatter

不修正已知 HtMl 标签的大小写。

[tool.djlint]
ignore_case=true

"ignore_case": true
--ignore_case

∞ include

linter

进行制定规则的代码检查。

include="H014,H015"
"include": "H014,H015"
--include "H014,H015"

∞ indent

formatter

代码缩进。默认4空格。

indent=3
"indent": "3"
--indent 3

∞ line_break_after_multiline_tag

formatter

不将多行标签的内容压缩到最后一个属性的行中。

line_break_after_multiline_tag=true
"line_break_after_multiline_tag": "true"
--line-break-after-multiline-tag

∞ linter_output_format

linter

自定义输出文本顺序。默认=“{code} {line} {message} {match}”。如果消息中不包含{filename}，则输出将按文件进行分组，并且每个分组会自动添加一个标题。

Optional variables:

  • {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

formatter

设置标签参数最大长度。

max_attribute_length=10
"max_attribute_length": "10"
--max-attribute-length 10

∞ max_blank_lines

formatter

将合并空行为最多 x 行。默认值为 0，表示将移除所有空行。

max_blank_lines=5
"max_blank_lines": 5
--max_blank_lines 5

∞ max_line_length

formatter

设置单行最大长度。

max_line_length=120
"max_line_length": "120"
--max_line_length 120

∞ no_function_formatting

formatter

不格式化函数。** 如果你使用了此选项，请在 GitHub 上打开一个 issue，解释你为什么使用它。

no_function_formatting=true
"no_function_formatting": true
--no-function-formatting

∞ no_line_after_yaml

formatter

在YAML front matter后不添加空行。

no_line_after_yaml=true
"no_line_after_yaml": true
--no-line-after-yaml

∞ no_set_formatting

formatter

不格式化集合（set）。** 如果你使用了此选项，请在 GitHub 上打开一个 issue，解释你为什么使用它。

no_set_formatting=true
"no_set_formatting": true
--no-set-formatting

∞ per_file_ignores

linter

某文件单独应用代码检查忽略规则。

[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" --per-file-ignores "file_two.html" "H001"

∞ preserve_blank_lines

formatter

尽可能保留文件开头的空行。（建议用于非HTML模板文件，它们的空行是有意为之的）

preserve_blank_lines=true
"preserve_blank_lines": true
--preserve_blank_lines

∞ preserve_leading_space

formatter

尽可能保留文本开头的空格。（建议用于非HTML模板文件，它们的缩进是有意为之的）

preserve_leading_space=true
"preserve_leading_space": true
--preserve_leading_space

∞ profile

linterformatter

为模板语言设置一个预设配置（profile）。该预设会应用于所有文件的代码检查与格式化中。例如，启用 handlebars 配置，则 {{#if}} 标签内部不包含空格。

Options:

  • html (default)
  • django
  • jinja
  • nunjucks (for nunjucks and twig)
  • handlebars (for handlebars and mustache)
  • golang
  • angular

profile="django"
"profile": "django"
--profile "django"

∞ quiet

formatterlinter

格式化时不展示差异。

--quiet

∞ require_pragma

formatter

只检查并格式化以 ‘djlint:on’ 注释开头的文件。该注释可为 HTML 注释或模板文件定义的注释，若无特殊模板文件，则使用模板语言的注释。

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

require_pragma=true
"require_pragma": true
--require_pragma

∞ use_gitignore

linterformatter

排除 .gitignore 规定的排除文件。

use_gitignore=true
"use_gitignore": true
--use_gitignore

∞ version

formatterlinter

显示版本并退出。

--version

∞ warn

formatterlinter

以警告形式报错。

--warn
编辑此页 最后更新 Jun 4, 2026