配置

可以通过项目的 pyproject.toml 文件、djlint.toml 或 .djlint.toml 文件,或者 .djlintrc 文件进行配置。命令行参数始终会覆盖配置文件中的任何设置。本地项目设置会覆盖通过 --configuration 指定的全局配置文件,除非设置了 --prefer-configuration。

djLint 从它检查的第一个路径(对 - 而言是 --stdin-filename 所在的文件夹,未指定时是当前目录)开始向上查找这些文件。它会在第一个包含 .git 文件夹或文件、.hg 文件夹、pyproject.toml、djlint.toml、.djlint.toml 或 .djlintrc 的文件夹处停下,并且只读取这个文件夹:先读 pyproject.toml 中的 [tool.djlint](其中有设置时),没有则读 djlint.toml 或 .djlint.toml,再没有则读 .djlintrc。因此,一个没有 djLint 设置的 pyproject.toml 会使上层文件夹中的配置文件不被读取。

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 表示 {% 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

在文件夹中查找的文件的扩展名。默认为 html。

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。

[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。模板语法尚未得到完全支持。type 既不是 JavaScript 也不是 JSON 的脚本(例如 text/template 中的客户端模板)保持原样。

[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}
  • {end}
  • {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

最多保留这么多行连续的空行。默认值为 0,即删除空行。启用 preserve_blank_lines 时此选项无效。

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。

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

为模板语言设置预设。预设会启用适用于你的模板语言的代码检查规则,也可能改变重新格式化的方式。例如,在 handlebars 中,{{#if}} 标签内部没有空格。

未设置预设时,djLint 会像 all 一样格式化所有模板语言的语法,并使用 html 的规则进行代码检查。

可选值:

  • 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 表达式永远不会被重新格式化)
  • mako(控制行和 ## 注释保持原样)
  • all(同时适用于所有模板语言)
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 设置所定义的模板语言中的注释。如果未指定预设,则接受任何一种模板语言中的注释。

<!-- 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

存在代码检查错误或需要重新格式化的文件时,以 0 而不是 1 退出。

--warn