配置
可以通过项目的 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
当给定的路径完全没有匹配到任何文件时,以 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
在 {% <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
在 {% <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
为已知的空元素标签添加闭合标记,使 <img> 变成 <img />。启用此选项时,不会报告要求相反写法的 H018。
close_void_tags=true
close_void_tags=true
"close_void_tags": true
--close-void-tags
custom_blocks
要缩进的自定义模板块的名称,例如 toc 表示 {% toc %}...{% endtoc %}。
custom_blocks="toc,example"
custom_blocks="toc,example"
"custom_blocks": "toc,example"
--custom-blocks "toc,example"
custom_html
要缩进的自定义 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
覆盖默认的排除路径。
exclude=".venv,venv,.tox,.eggs,..."
exclude=".venv,venv,.tox,.eggs,..."
"exclude": ".venv,venv,.tox,.eggs,..."
--exclude ".venv,venv,.tox,.eggs,..."
extend_exclude
在默认的排除路径之外添加其他路径。
extend_exclude=".custom"
extend_exclude=".custom"
"extend_exclude": ".custom"
--extend-exclude ".custom"
extension
在文件夹中查找的文件的扩展名。默认为 html。
extension="html.dj"
extension="html.dj"
"extension": "html.dj"
--extension "html.dj"
# or
-e "html.dj"
files
用作 djlint 源的路径列表。指定此选项时,命令行中的源必须是 -,就像使用 stdin 时一样。如果给出了 --stdin-filename,即使设置了此选项,- 也会读取 stdin。
[tool.djlint]
files=["index.html"]
files=["index.html"]
"files": [
"index.html"
]
index.html
format_attribute_js_json
格式化 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
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
用于匹配要格式化的 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
格式化标签属性中的模板语法。默认禁用。
format_attribute_template_tags=true
format_attribute_template_tags=true
"format_attribute_template_tags": true
--format-attribute-template-tags
format_css
使用 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
使用 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
要跳过的代码检查规则代码。
ignore="H014,H015"
ignore="H014,H015"
"ignore": "H014,H015"
--ignore "H014,H015"
ignore_blocks
不为其内容增加缩进的模板块。其子元素被视为该块的同级元素,并相应地缩进。
ignore_blocks="raw,example"
ignore_blocks="raw,example"
"ignore_blocks": "raw,example"
--ignore-blocks "raw,example"
ignore_case
不尝试修正已知 html 标签的大小写。启用此选项时,不会报告 H009 和 H010。
[tool.djlint]
ignore_case=true
ignore_case=true
"ignore_case": true
--ignore-case
include
要启用的代码检查规则代码,包括默认关闭的规则和预设未包含的规则。
include="H014,H015"
include="H014,H015"
"include": "H014,H015"
--include "H014,H015"
indent
每级缩进的空格数。默认值为 4,或项目根目录下 .editorconfig 中的 indent_size。
indent=3
indent=3
"indent": 3
--indent 3
keep_br_inline
让 <br> 留在它所断开的文本所在的行,而不是单独占一行。<hr> 会渲染为前面内容下方的一条横线,不受影响。
keep_br_inline=true
keep_br_inline=true
"keep_br_inline": true
--keep-br-inline
line_break_after_multiline_tag
当标签的属性分布在多行时,让其内容另起一行。
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
自定义输出消息的顺序。默认值为 “{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
当标签的属性长度超过此值时,格式化工具会把它们分到多行。默认值为 70。
max_attribute_length=10
max_attribute_length=10
"max_attribute_length": 10
--max-attribute-length 10
max_blank_lines
最多保留这么多行连续的空行。默认值为 0,即删除空行。启用 preserve_blank_lines 时此选项无效。
max_blank_lines=5
max_blank_lines=5
"max_blank_lines": 5
--max-blank-lines 5
max_line_length
只有当整行不超过此长度时,格式化工具才会把一些 HTML 和模板标签合并到一行。默认值为 120,或项目根目录下 .editorconfig 中的 max_line_length。
max_line_length=120
max_line_length=120
"max_line_length": 120
--max-line-length 120
name_endblocks
对于跨多行书写的块,把块的名称写入关闭它的 {% endblock %} 中。这正是 T003 所要求的。
name_endblocks=true
name_endblocks=true
"name_endblocks": true
--name-endblocks
no_entity_formatting
不把实体引用改写为它所表示的字符,因此 © 会保持原样,而不会变成 ©。承载语法的实体和不可见字符的实体,无论如何都不会被改写。启用此选项时,H023 仍会报告实体;要保留实体,请把 H023 添加到 ignore 中。
no_entity_formatting=true
no_entity_formatting=true
"no_entity_formatting": true
--no-entity-formatting
no_function_formatting
不尝试格式化 {{ }} 表达式中函数调用的参数。
no_function_formatting=true
no_function_formatting=true
"no_function_formatting": true
--no-function-formatting
no_indent_inner_html
不在 <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
不在 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
不尝试格式化 {% set %} 标签的内容。
no_set_formatting=true
no_set_formatting=true
"no_set_formatting": true
--no-set-formatting
per_file_ignores
按文件忽略代码检查规则。
[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
让 configuration 指定的文件覆盖项目自身的配置文件。configuration 指定的是一个全局文件,因此默认情况下,当两者设置了同一项时,模板旁边的 pyproject.toml 或 .djlintrc 优先。仅限命令行使用,因为它决定的是配置文件本身如何被读取。
--prefer-configuration
preserve_blank_lines
尽可能保留空行。非常适合空行有意为之的非 html 模板文件。
preserve_blank_lines=true
preserve_blank_lines=true
"preserve_blank_lines": true
--preserve-blank-lines
preserve_class_newlines
保留多行 class 属性中的换行。
preserve_class_newlines=true
preserve_class_newlines=true
"preserve_class_newlines": true
--preserve-class-newlines
preserve_leading_space
尽可能保留文本的前导空格。非常适合文本缩进有意为之的非 html 模板文件。
preserve_leading_space=true
preserve_leading_space=true
"preserve_leading_space": true
--preserve-leading-space
profile
为模板语言设置预设。预设会启用适用于你的模板语言的代码检查规则,也可能改变重新格式化的方式。例如,在 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
不打印差异、进度条和汇总。
quiet=true
quiet=true
"quiet": true
--quiet
quote_style
模板标签内字符串使用的引号,可以是 double(默认)或 single。T002 要求使用相同的引号。格式化工具在条件中也会使用这种引号,例如 {% if x == "a" %},这样同一个文件中同一个字符串就不会有两种写法。HTML 属性的引号交由 H008 处理。
quote_style="single"
quote_style="single"
"quote_style": "single"
--quote-style single
require_pragma
只格式化或检查以一条注释开头、且该注释仅包含文本 ‘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
当开始标签需要换行时,把标签名、每个属性和结束尖括号分别放在单独的行上。默认禁用。
single_attribute_per_line=true
single_attribute_per_line=true
"single_attribute_per_line": true
--single-attribute-per-line
sort_attributes
按名称对属性排序,id 排在第一位,class 排在第二位。如果标签的属性受模板标签控制,则保持原有的书写顺序,因为把属性移出其所在的分支会改变页面。
sort_attributes=true
sort_attributes=true
"sort_attributes": true
--sort-attributes
sort_load_tags
对 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
代表 stdin 的路径,用于消息,以及与排除路径和 per-file-ignores 的匹配。默认为 “-”。
--stdin-filename templates/index.html
use_gitignore
将 .gitignore 中的排除项添加到默认的排除列表中。默认禁用。
use_gitignore=true
use_gitignore=true
"use_gitignore": true
--use-gitignore