配置

配置可通过项目的 pyproject.toml 文件、djlint.toml 或 .djlint.toml 文件，或 .djlintrc 文件来完成。命令行参数优先级大于配置文件的任何配置，本地项目设置优先级大于通过 --configuration 指定的全局配置文件，除非设置了 --prefer-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 退出。（默认关闭）

allow_empty_input=true
allow_empty_input=true
"allow_empty_input": true
--allow-empty-input

blank_line_after_tag

自 0.4.2formatter

在 {% <tag> ... %} 标签组后添加空行。（空行不会添加到块的末尾）

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> ... %} 标签组前添加空行。（空行不会添加到文件或块的开头，也不会添加到同一个标签之间）

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。

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

custom_blocks

自 0.3.5formatter

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

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+>。

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

覆盖默认排除路径。

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

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

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

extension

自 0.0.5linterformatter

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

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

files

自 1.14.0linterformatter

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

[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 的对象不会被格式化。

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。属性数量更少的对象会保持在单行。

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 属性的自定义正则表达式。默认模式会匹配常见 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-js-json-pattern "^(on[a-z]+|data-[a-z-]+|x-[a-z-]+)$"

format_attribute_template_tags

自 0.6.7formatter

尝试格式化标签属性中的模板语法。（默认关闭）

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，目前模板语法并未得到完全支持。

[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，目前模板语法并未得到完全支持。

[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

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

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

ignore_blocks

自 1.24.0formatter

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

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

ignore_case

自 1.23.0formatterlinter

不修正已知 HTML 标签的大小写。启用后不报告 H009 和 H010。

[tool.djlint]
ignore_case=true

ignore_case=true
"ignore_case": true
--ignore-case

include

自 1.20.0linter

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

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

indent

自 0.3.5formatter

代码缩进。默认 4 个空格，或项目根目录 .editorconfig 中的 indent_size。

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

keep_br_inline

自 1.45.0formatter

让 <br> 留在它所断开的那行文本上，而不是单独占一行。<hr> 会在前面内容下方渲染成一条横线，不受影响。

keep_br_inline=true
keep_br_inline=true
"keep_br_inline": true
--keep-br-inline

line_break_after_multiline_tag

自 1.27.0formatter

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

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}
  • {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}"
--linter-output-format "{filename}:{line}: {code} {message} {match}"

max_attribute_length

自 0.5.8formatter

设置标签参数最大长度。默认值为 70。

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

max_blank_lines

自 1.31.0formatter

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

max_blank_lines=5
max_blank_lines=5
"max_blank_lines": 5
--max-blank-lines 5

max_line_length

自 0.5.7formatter

设置单行最大长度。默认值为 120，或项目根目录 .editorconfig 中的 max_line_length。

max_line_length=120
max_line_length=120
"max_line_length": 120
--max-line-length 120

name_endblocks

自 1.45.0formatter

当块跨越多行时，把块名写入关闭它的 {% endblock %}。这正是 T003 的要求。

name_endblocks=true
name_endblocks=true
"name_endblocks": true
--name-endblocks

no_entity_formatting

自 1.45.0formatter

不把实体引用改写成它所指代的字符，&copy; 保持原样而不会变成 ©。承载语法的实体和不可见实体在任何情况下都不会被改写。H023 仍会报告实体；若要保留实体，请把 H023 加入 ignore。

no_entity_formatting=true
no_entity_formatting=true
"no_entity_formatting": true
--no-entity-formatting

no_function_formatting

自 1.30.2formatter

不格式化 {{ }} 表达式中函数调用的参数。

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

no_indent_inner_html

自 1.45.0formatter

不缩进 <html> 下的 <head> 与 <body>，与 VS Code 默认 html 格式化器的排版一致。

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后不添加空行。

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 %} 标签中的内容。

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

per_file_ignores

自 1.7.0linter

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

[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模板文件，它们的空行是有意为之的）

preserve_blank_lines=true
preserve_blank_lines=true
"preserve_blank_lines": true
--preserve-blank-lines

preserve_class_newlines

自 1.39.0formatter

保留多行 class 属性中的换行。

preserve_class_newlines=true
preserve_class_newlines=true
"preserve_class_newlines": true
--preserve-class-newlines

preserve_leading_space

自 1.2.0formatter

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

preserve_leading_space=true
preserve_leading_space=true
"preserve_leading_space": true
--preserve-leading-space

profile

自 0.4.5linterformatter

为模板语言设置一个预设配置（profile）。该预设会启用适用于你的模板语言的检查规则，也可能改变格式化方式。例如，启用 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 表达式永远不会被重新格式化）
profile="django"
profile="django"
"profile": "django"
--profile "django"

quiet

自 0.0.9formatterlinter

格式化时不展示差异。

quiet=true
quiet=true
"quiet": true
--quiet

quote_style

自 1.45.0formatterlinter

模板标签内字符串使用的引号，可选 double（默认）或 single。T002 要求同样的引号。格式化器在条件中也使用它们，例如 {% if x == "a" %}，使同一文件不会把同一字符串写成两种形式。HTML 属性的引号由 H008 管理。

quote_style="single"
quote_style="single"
"quote_style": "single"
--quote-style single

require_pragma

自 0.5.8formatter

只检查并格式化以 ‘djlint:on’ 注释开头的文件。该注释可以是 HTML 注释，也可以是 profile 设置所指定模板语言的注释。若未指定 profile，则接受任一模板语言的注释。

<!-- djlint:on -->
{# djlint:on #}
{% comment %} djlint:on {% endcomment %}
{{ /* djlint:on */ }}
{{!-- djlint:on --}}
require_pragma=true
require_pragma=true
"require_pragma": true
--require-pragma

single_attribute_per_line

自 1.40.0formatter

当开始标签换行时，将标签名、每个属性和结束括号分别放在单独的行上。默认禁用。

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 次之。属性被模板标签包裹的标签保持原有顺序，因为把属性移出其分支会改变页面。

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 之前的名称。若两个库定义了同名的标签或过滤器，最后加载的生效，因此排序可能改变模板使用的是哪一个。

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 规定的排除文件。（默认关闭）

use_gitignore=true
use_gitignore=true
"use_gitignore": true
--use-gitignore

version

自 0.3.9formatterlinter

显示版本并退出。

--version

warn

自 0.7.6formatterlinter

以警告形式报错。

--warn