Перейти к содержимому

Конфигурация

Настройки задаются в pyproject.toml вашего проекта, в djlint.toml или .djlint.toml либо в .djlintrc. Параметры командной строки переопределяют файл конфигурации, но флаг может только включить параметр, поэтому выключить переключатель, включённый в файле конфигурации, им нельзя. Настройки проекта переопределяют глобальный файл конфигурации, заданный через --configuration, если не указан --prefer-configuration.

djLint ищет эти файлы вверх от первого проверяемого пути (для - от папки из --stdin-filename, а без этого параметра от текущего каталога). Поиск останавливается на первой папке, где есть djlint.toml, .djlint.toml, .djlintrc, .djlint_rules.yaml или pyproject.toml с [tool.djlint], и никогда не выходит за корень репозитория (папку, где есть папка или файл .git или папка .hg). pyproject.toml без настроек djLint поиск не останавливает, так что пакет в монорепозитории со своим pyproject.toml получает настройки репозитория. Читается только папка, где поиск остановился: [tool.djlint] из её pyproject.toml, если в этой таблице что-то задано, иначе её djlint.toml или .djlint.toml, а если нет и их, то её .djlintrc. О файлах, которые лежат там же, но не читаются, djLint предупреждает.

Если ни командная строка, ни конфигурация не задают indent или max_line_length, djLint берёт indent_size или max_line_length из файлов .editorconfig, как это делают редакторы: каждый файл получает их по своему пути, ближайший .editorconfig главнее, а те, что выше, дополняют его, вплоть до файла с root = true или корня проекта.

Файл pyproject.toml записывается в формате toml.

[tool.djlint]
profile = "django"
ignore = ["H014", "H015"]

Файлы djlint.toml и .djlint.toml записываются в формате toml.

profile = "django"
ignore = ["H014", "H015"]

Файл .djlintrc записывается в формате json.

{ "profile": "django", "ignore": ["H014", "H015"] }

Параметры с несколькими значениями, например ignore, принимают список. Строка через запятую вроде "H014,H015" тоже работает, а djLint до 1.41 понимает только её.

С версии 1.51 djLint предупреждает о незнакомом параметре или коде правила и подсказывает ближайший известный.

allow_empty_input

с версии 1.44.0 formatter linter --allow-empty-input

По умолчанию: false

Завершаться с кодом 0, а не 2, если заданные пути вообще не совпадают ни с одним файлом. Если файлы были найдены, а затем пропущены из-за exclude, extend_exclude, use_gitignore или require_pragma, код завершения и так 0.

allow_empty_input=true

blank_line_after_tag

с версии 0.4.2 formatter --blank-line-after-tag

По умолчанию: нет

Теги шаблона, после которых добавляется пустая строка, например load и extends. Если несколько таких тегов идут подряд, строка добавляется после последнего, а в конце блока она не добавляется.

blank_line_after_tag=["load", "extends", "include"]

blank_line_before_tag

с версии 1.8.0 formatter --blank-line-before-tag

По умолчанию: нет

Теги шаблона, перед которыми добавляется пустая строка, например load и extends. Если несколько таких тегов идут подряд, строка добавляется перед первым, а в начале файла или блока она не добавляется.

blank_line_before_tag=["load", "extends", "include"]

close_void_tags

с версии 1.26.0 formatter linter --close-void-tags

По умолчанию: false

Закрывать известные пустые теги косой чертой, так что <img> превращается в <img />. Правило H018, которое требует обратного, при этом не срабатывает.

close_void_tags=true

configuration

с версии 1.13.0 formatter linter --configuration

Глобальный файл конфигурации, pyproject.toml, djlint.toml или .djlintrc, например в вашей домашней папке. Если параметр задан в обоих файлах, приоритет у собственного файла конфигурации проекта, кроме случая, когда включён prefer_configuration.

Окно терминала
--configuration ~/.djlintrc

custom_blocks

с версии 0.3.5 formatter --custom-blocks

По умолчанию: нет

Имена пользовательских блоков шаблона, для которых добавляются отступы, например toc для {% toc %}...{% endtoc %}.

custom_blocks=["toc", "example"]

custom_html

с версии 0.7.0 formatter --custom-html

По умолчанию: нет

Имена пользовательских HTML-тегов, для которых добавляются отступы, например mjml или simple-greeting. Имя может быть регулярным выражением, как mj-\w+.

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

exclude

с версии 0.4.0 linter formatter --exclude

По умолчанию: "__pypackages__,_build,_site,.bzr,.direnv,.eggs,.git,.git-rewrite,.hg,.nox,.svn,.tox,.venv,build,dist,htmlcov,node_modules,site-packages,venv"

Пути, которые нужно пропустить, вместо списка по умолчанию. Каждая запись является регулярным выражением, которое сопоставляется с целыми именами папок или файлов в пути относительно корня проекта или проверяемой папки, например vendor или templates/legacy, поэтому *.min.html записывается как .*\.min\.html.

exclude=[".venv", "venv", "build"]

extend_exclude

с версии 0.4.0 linter formatter --extend-exclude

По умолчанию: нет

Пути, которые нужно пропустить, в дополнение к exclude или, если exclude не задан, к списку по умолчанию, в виде регулярных выражений, как в exclude.

extend_exclude=[".custom"]

extension

с версии 0.0.5 linter formatter --extension

По умолчанию: "html"

Расширение файлов, которые ищутся в папках. Принимает одно расширение; файл, переданный по имени, проверяется независимо от его расширения.

extension="html.dj"

files

с версии 1.14.0 linter formatter

По умолчанию: нет

Пути для проверки вместо путей из командной строки, где тогда нужно указать -, как для stdin. С --stdin-filename - в любом случае означает stdin.

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

format_attribute_js_json

с версии 1.37.0 formatter --format-attribute-js-json

По умолчанию: false

Также форматировать JavaScript и JSON в атрибутах вроде onclick и x-data, то есть в тех, что задаёт format_attribute_js_json_pattern. Объект, у которого меньше свойств, чем format_attribute_js_json_min_props, остаётся на одной строке.

format_attribute_js_json=true

format_attribute_js_json_min_props

с версии 1.37.0 formatter --format-attribute-js-json-min-props

По умолчанию: 2

Форматировать объект, только если у него не меньше указанного числа свойств. Объект с меньшим числом свойств остаётся на одной строке.

format_attribute_js_json_min_props=3

format_attribute_js_json_pattern

с версии 1.37.0 formatter --format-attribute-js-json-pattern

По умолчанию: "^(?:on[a-z]+|x-[a-z\\-]+|@[a-z\\-]+|:[a-z\\-]+|v-[a-z\\-]+|\\([a-z\\-]+\\)|\\[[a-z\\-]+\\]|\\*ng[A-Z][a-zA-Z]*|[a-z\\-]+\\.(bind|delegate|call|trigger))$"

Регулярное выражение для имён атрибутов, которые нужно форматировать как JavaScript или JSON. Выражение по умолчанию охватывает обработчики событий on* и привязки Alpine, Vue, Angular и Aurelia.

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

format_attribute_template_tags

с версии 0.6.7 formatter --format-attribute-template-tags

По умолчанию: false

Форматировать синтаксис шаблона внутри атрибутов тегов.

format_attribute_template_tags=true

format_css

с версии 1.9.0 formatter --format-css

По умолчанию: false

Также форматировать содержимое тегов <style> с помощью css-beautify. Синтаксис шаблонов внутри них поддерживается не полностью.

Отступ внутри тегов <style> задаёт indent_size в таблице css или --indent-css в командной строке, по умолчанию 4. Таблица принимает и остальные параметры css-beautify.

[tool.djlint]
format_css=true
[tool.djlint.css]
indent_size=5

format_js

с версии 1.9.0 formatter --format-js

По умолчанию: false

Также форматировать JavaScript и JSON в тегах <script> с помощью js-beautify. Скрипт, у которого type не JavaScript и не JSON, например клиентский шаблон в text/template, остаётся как есть. Синтаксис шаблонов внутри них поддерживается не полностью.

Отступ внутри тегов <script> задаёт indent_size в таблице js или --indent-js в командной строке, по умолчанию 4. Таблица принимает и остальные параметры js-beautify.

[tool.djlint]
format_js=true
[tool.djlint.js]
indent_size=5

github_output

с версии 1.37.0 formatter linter --github-output

По умолчанию: нет

Выводить результаты в виде аннотаций GitHub Actions. Внутри GitHub Actions это включено по умолчанию, а --no-github-output это отключает. См. GitHub Actions.

Окно терминала
--github-output

ignore

с версии 0.1.5 linter --ignore

По умолчанию: нет

Коды правил линтера, которые нужно пропустить.

ignore=["H014", "H015"]

ignore_blocks

с версии 1.24.0 formatter --ignore-blocks

По умолчанию: нет

Блоки шаблона, которые не добавляют отступ своему содержимому. Дочерние элементы считаются соседними с блоком и получают соответствующий отступ.

ignore_blocks=["raw", "example"]

ignore_case

с версии 1.23.0 formatter linter --ignore-case

По умолчанию: false

Не исправлять регистр известных HTML-тегов. Правила H009 и H010 при этом не срабатывают.

[tool.djlint]
ignore_case=true

include

с версии 1.20.0 linter --include

По умолчанию: нет

Коды правил линтера, которые нужно включить: выключенных по умолчанию или не входящих в профиль.

include=["H014", "H015"]

indent

с версии 0.3.5 formatter --indent

По умолчанию: 4

Число пробелов на уровень отступа. Если параметр не задан, djLint берёт indent_size, заданный для файла в .editorconfig, если такой есть.

indent=3

keep_br_inline

с версии 1.45.0 formatter --keep-br-inline

По умолчанию: false

Оставлять <br> на одной строке с текстом, который он разрывает, а не выносить его на отдельную строку. На <hr>, который отображается как линия под предшествующим содержимым, это не влияет.

keep_br_inline=true

line_break_after_multiline_tag

с версии 1.27.0 formatter --line-break-after-multiline-tag

По умолчанию: false

Когда атрибуты тега разнесены по строкам, начинать его содержимое с новой строки.

line_break_after_multiline_tag=true

linter_output_format

с версии 0.6.7 linter --linter-output-format

По умолчанию: "{code} {line} {message} {match}"

Формат каждого сообщения линтера, собранный из {filename}, {line}, {end}, {code}, {message} и {match}. Без {filename} вывод группируется по файлам, и к каждой группе добавляется заголовок.

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

max_attribute_length

с версии 0.5.8 formatter --max-attribute-length

По умолчанию: 70

Когда атрибуты тега длиннее этого значения, форматер разносит их по строкам.

max_attribute_length=10

max_blank_lines

с версии 1.31.0 formatter --max-blank-lines

По умолчанию: 0

Оставлять не больше указанного числа пустых строк подряд, так что при 0 они удаляются. Не действует при preserve_blank_lines.

max_blank_lines=5

max_line_length

с версии 0.5.7 formatter --max-line-length

По умолчанию: 120

Форматер собирает некоторые HTML-теги и теги шаблона в одну строку, только если она укладывается в эту длину. Если параметр не задан, djLint берёт max_line_length, заданный для файла в .editorconfig, если такой есть.

max_line_length=100

name_endblocks

с версии 1.45.0 formatter --name-endblocks

По умолчанию: false

Дописывать имя блока в закрывающий его {% endblock %}, если блок занимает несколько строк. Именно этого требует T003.

name_endblocks=true

no_entity_formatting

с версии 1.45.0 formatter --no-entity-formatting

По умолчанию: false

Не заменять мнемонику символом, который она обозначает, чтобы &copy; оставалась как написано, а не превращалась в ©. Мнемоники, несущие синтаксическую роль, и мнемоники невидимых символов не заменяются в любом случае. H023 при этом всё равно сообщает о мнемонике; чтобы сохранить мнемоники, добавьте H023 в ignore.

no_entity_formatting=true

no_function_formatting

с версии 1.30.2 formatter --no-function-formatting

По умолчанию: false

Не форматировать аргументы вызовов функций внутри {{ }}.

no_function_formatting=true

no_indent_inner_html

с версии 1.45.0 formatter --no-indent-inner-html

По умолчанию: false

Не добавлять отступ для <head> и <body> внутри <html>: так документ оформляет встроенный HTML-форматер VS Code.

no_indent_inner_html=true

no_line_after_yaml

с версии 1.29.0 formatter --no-line-after-yaml

По умолчанию: false

Не добавлять пустую строку после front matter на YAML.

no_line_after_yaml=true

no_set_formatting

с версии 1.30.2 formatter --no-set-formatting

По умолчанию: false

Не форматировать содержимое тегов {% set %}.

no_set_formatting=true

per_file_ignores

с версии 1.7.0 linter --per-file-ignores

По умолчанию: нет

Коды правил линтера, которые нужно пропустить в файлах, чей путь совпадает с регулярным выражением. В файле конфигурации ключ пишется через дефисы: per-file-ignores.

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

prefer_configuration

с версии 1.45.0 formatter linter --prefer-configuration

По умолчанию: false

Позволить файлу, указанному в --configuration, переопределять собственный файл конфигурации проекта, у которого по умолчанию приоритет, если оба задают один и тот же параметр. Только для командной строки, поскольку этот параметр определяет, как читаются сами файлы конфигурации.

Окно терминала
--prefer-configuration

preserve_blank_lines

с версии 1.3.0 formatter --preserve-blank-lines

По умолчанию: false

По возможности сохранять пустые строки. Полезно для шаблонов не в формате HTML, где пустые строки оставлены намеренно.

preserve_blank_lines=true

preserve_class_newlines

с версии 1.39.0 formatter --preserve-class-newlines

По умолчанию: false

Сохранять переносы строк в атрибутах class, записанных на нескольких строках.

preserve_class_newlines=true

preserve_leading_space

с версии 1.2.0 formatter --preserve-leading-space

По умолчанию: false

По возможности сохранять пробелы в начале строк текста. Полезно для шаблонов не в формате HTML, где отступы текста сделаны намеренно.

preserve_leading_space=true

profile

с версии 0.4.5 linter formatter --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 (шаблоны в стиле jinja на rust; выражения rust никогда не переформатируются)
  • mako (управляющие строки и комментарии ## остаются как есть)
  • all (все языки шаблонов сразу)
profile="django"

quiet

с версии 0.0.9 formatter linter --quiet

По умолчанию: false

Не выводить diff, индикатор прогресса и итоговую сводку.

quiet=true

quote_style

с версии 1.45.0 formatter linter --quote-style

По умолчанию: "double"

Кавычки для строк внутри тегов шаблона: double или single. T002 требует тех же кавычек, а форматер использует их в условиях, например {% if x == "a" %}, чтобы в одном файле одна и та же строка не записывалась двумя способами. За кавычки в HTML-атрибутах отвечает H008.

quote_style="single"

require_pragma

с версии 0.5.8 formatter linter --require-pragma

По умолчанию: false

Форматировать или проверять только файлы, которые начинаются с комментария djlint:on. Это может быть HTML-комментарий или комментарий на языке шаблонов, заданном в profile, а если профиль не задан, то на любом из этих языков.

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

rules

с версии 1.41.0 formatter linter --rules

Файл пользовательских правил в формате .djlint_rules.yaml, который читается вместо файла в корне проекта.

Окно терминала
--rules ../shared/.djlint_rules.yaml

sarif

с версии 1.46.0 formatter linter --sarif

По умолчанию: false

Выводить замечания в виде документа SARIF 2.1.0 для сканирования кода на GitHub и других инструментов. См. GitHub Actions.

Окно терминала
--sarif

single_attribute_per_line

с версии 1.40.0 formatter --single-attribute-per-line

По умолчанию: false

Когда открывающий тег переносится, размещать имя тега, каждый атрибут и закрывающую скобку на отдельных строках.

single_attribute_per_line=true

sort_attributes

с версии 1.45.0 formatter --sort-attributes

По умолчанию: false

Сортировать атрибуты по имени, ставя id первым, а class вторым. Если атрибуты тега обёрнуты в тег шаблона, сохраняется исходный порядок, поскольку перенос атрибута из его ветки изменил бы страницу.

sort_attributes=true

sort_load_tags

с версии 1.47.0 formatter --sort-load-tags

По умолчанию: false

Сортировать библиотеки в тегах {% load %} и удалять повторы, так что {% load static i18n %} превращается в {% load i18n static %}. В {% load a b from library %} сортируются имена перед from. Если две библиотеки определяют тег или фильтр с одинаковым именем, действует та, что загружена последней, поэтому сортировка может изменить, какой из них используется в шаблоне.

sort_load_tags=true

statistics

с версии 1.16.0 linter --statistics

По умолчанию: false

После проверки выводить, сколько раз найден каждый код.

Окно терминала
--statistics

stdin_filename

с версии 1.43.0 formatter linter --stdin-filename

По умолчанию: "-"

Путь, которым считается stdin в сообщениях и при сверке с exclude и per-file-ignores.

Окно терминала
--stdin-filename templates/index.html

use_gitignore

с версии 0.5.9 linter formatter --use-gitignore

По умолчанию: false

Также пропускать пути, перечисленные в .gitignore в корне проекта.

use_gitignore=true

version

с версии 0.3.9 formatter linter --version

Показать версию и выйти.

Окно терминала
--version

warn

с версии 0.7.6 formatter linter --warn

По умолчанию: false

Завершаться с кодом 0 вместо 1, когда линтер нашёл ошибки или есть файлы для переформатирования.

Окно терминала
--warn