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

Интеграции

Какой бы редактор вы ни использовали, установите djLint туда, где редактор сможет его найти, лучше всего в виртуальное окружение проекта, и запускайте редактор из этого окружения или укажите ему djlint из него. Тогда редактор будет запускать версию, зафиксированную в проекте, и результаты совпадут с результатами хука pre-commit или CI.

Если djLint в проекте установлен через npm, его команда лежит в проекте: node_modules/.bin/djlint, а на Windows node_modules\.bin\djlint.cmd. Там, где редактор ниже запускает djlint, укажите ему этот путь. Расширения для VS Code и Zed находят его сами.

Установите расширение djLint из Visual Studio Marketplace. Cursor, Windsurf, VSCodium и другие редакторы на основе VS Code ставят то же расширение из Open VSX. Оно ищет djLint в вашем окружении и, если не находит, использует встроенный. Если ваша версия djLint поддерживает языковой сервер, расширение работает через него.

В его README описаны настройки расширения и то, какой djLint оно запускает.

Расширение djLint запускает языковой сервер в HTML и в языках шаблонных расширений, например Django, Jinja и Twig. В реестре расширений Zed его пока нет, поэтому установите его как dev-расширение:

  1. Установите Rust через rustup: Zed собирает им расширение и сам добавляет таргет wasm32-wasip2. Если Rust установлен иначе, например через Homebrew или Nix, добавьте таргет сами.

  2. Склонируйте расширение:

    Окно терминала
    git clone https://github.com/djlint/djlint-zed
  3. Откройте в Zed палитру команд (cmd-shift-p на macOS, ctrl-shift-p в остальных системах), выполните zed: install dev extension и выберите склонированную папку djlint-zed.

Чтобы обновить расширение, выполните в этой папке git pull, а затем zed: rebuild dev extension.

Нужен djLint 1.49 или новее в PATH или установленный в проекте через npm, либо uv, который запускает djLint без установки. В README расширения описано, как назначить его форматером языка, и перечислены его настройки.

Некоторым расширениям шаблонов Neovim не назначает filetype. Какой бы вариант ниже вы ни выбрали, сначала зарегистрируйте их:

vim.filetype.add({
extension = {
gohtml = "gotmpl", gotmpl = "gotmpl", handlebars = "handlebars",
j2 = "jinja", jinja2 = "jinja", mako = "mako", njk = "nunjucks",
},
})

Neovim 0.11 и новее может работать с языковым сервером djLint напрямую, без плагинов. Так замечания появляются прямо во время набора, с подчёркиванием проблемных фрагментов, а форматирование выполняет vim.lsp.buf.format():

vim.lsp.config("djlint", {
cmd = { "djlint", "--lsp" },
filetypes = {
"html", "htmldjango", "htmlangular", "jinja", "jinja.html", "nunjucks",
"twig", "handlebars", "mustache", "liquid", "gotmpl", "tera", "mako",
},
root_markers = { "pyproject.toml", "djlint.toml", ".djlint.toml", ".djlintrc", ".git" },
})
vim.lsp.enable("djlint")

Чтобы форматировать при сохранении, добавьте в ту же конфигурацию:

local group = vim.api.nvim_create_augroup("djlint_format", {})
vim.api.nvim_create_autocmd("LspAttach", {
callback = function(args)
if vim.lsp.get_client_by_id(args.data.client_id).name ~= "djlint" then
return
end
vim.api.nvim_clear_autocmds({ group = group, buffer = args.buf })
vim.api.nvim_create_autocmd("BufWritePre", {
group = group,
buffer = args.buf,
callback = function()
vim.lsp.buf.format({ bufnr = args.buf, name = "djlint" })
end,
})
end,
})

См. раздел Настройки.

conform.nvim форматирует, а nvim-lint проверяет код, запуская djLint как команду. Замечания приходят без подчёркивания фрагментов и только тогда, когда вы запускаете проверку в nvim-lint. Профиль берётся из конфигурации проекта, как в командной строке. Этому примеру нужен djLint 1.49 или новее.

local formatters, linters = {}, {}
for _, filetype in ipairs({
"html", "htmldjango", "htmlangular", "jinja", "jinja.html", "nunjucks",
"twig", "handlebars", "mustache", "liquid", "gotmpl", "tera", "mako",
}) do
formatters[filetype] = { "djlint" }
linters[filetype] = { "djlint" }
end
require("conform").setup({
formatters_by_ft = formatters,
formatters = { djlint = { prepend_args = { "--stdin-filename", "$FILENAME" } } },
})
local lint = require("lint")
lint.linters_by_ft = linters
vim.list_extend(lint.linters.djlint.args, {
"--stdin-filename",
function()
return vim.api.nvim_buf_get_name(0)
end,
})

В PyCharm и других IDE на базе IntelliJ используйте бесплатный плагин LSP4IJ:

  1. Установите LSP4IJ из Marketplace.

  2. Откройте окно инструментов LSP Consoles и добавьте новый языковой сервер.

  3. На вкладке Server укажите имя djLint и команду djlint --lsp, с полным путём к djlint в виртуальном окружении проекта, если его нет в PATH.

  4. На вкладке Mappings добавьте маски имён файлов ваших шаблонов. Если в конфигурации проекта не задан профиль, его выбирает идентификатор языка у маски:

    Маски Идентификатор языка
    *.html, *.htm html, в Django htmldjango
    *.jinja, *.jinja2, *.j2 jinja
    *.njk, *.twig nunjucks
    *.hbs, *.handlebars, *.mustache handlebars
    *.liquid liquid
    *.gotmpl, *.gohtml gotmpl
    *.tera tera
    *.mako mako
  5. На вкладке Configuration можно задать настройки в формате JSON, в ключе djlint.

Замечания появляются в редакторе, а Reformat Code может использовать сервер для сопоставленных файлов.

Пакет LSP запускает языковой сервер, который показывает замечания во время набора и форматирует код.

Выполните Preferences: LSP Server Configurations и добавьте:

{ "djlint": { "enabled": true, "command": ["djlint", "--lsp"], "selector": "text.html" } }

Установите через Package Control SublimeLinter и SublimeLinter-contrib-djlint. djLint должен быть в PATH, который видит Sublime Text.

Helix может запускать языковой сервер, настроенный в languages.toml. Список language-servers заменяет тот, что есть у Helix для этого языка, поэтому оставьте после djlint его собственные серверы:

[language-server.djlint]
command = "djlint"
args = ["--lsp"]
[[language]]
name = "html"
language-servers = ["djlint", "vscode-html-language-server", "superhtml"]
[[language]]
name = "htmldjango"
language-servers = ["djlint", "djlsp", "vscode-html-language-server", "superhtml"]
[[language]]
name = "gotmpl"
language-servers = ["djlint", "gopls"]
[[language]]
name = "jinja"
language-servers = ["djlint"]
[[language]]
name = "nunjucks"
language-servers = ["djlint"]
[[language]]
name = "twig"
language-servers = ["djlint"]
[[language]]
name = "tera"
language-servers = ["djlint"]

Сам Helix не открывает ни один файл как htmldjango. В проекте на Django добавьте file-types = ["html"] к этой записи в .helix/languages.toml проекта.

Eglot, входящий в состав Emacs 29 и новее:

(with-eval-after-load 'eglot
(dolist (mode '(html-mode mhtml-mode web-mode jinja2-mode twig-mode
handlebars-mode mustache-mode))
(add-to-list 'eglot-server-programs `(,mode . ("djlint" "--lsp")))))

Затем выполните M-x eglot в шаблоне. eglot-format-buffer отформатирует его. html-mode, mhtml-mode и web-mode не называют язык шаблонов, поэтому в них профиль берётся из конфигурации проекта.

djlint --lsp запускает djLint как языковой сервер, работающий через stdio. Сервер работает постоянно, поэтому редактор получает замечания во время набора и форматирует документ, не запуская каждый раз новый процесс.

Сервер сообщает о замечаниях и форматирует документы целиком. Дополнительные пакеты ему не нужны. Любой другой редактор с поддержкой LSP может запустить его той же командой.

Сервер читает конфигурацию проекта так же, как командная строка: от папки каждого файла вверх. Настройки из редактора важнее неё, но, как и в командной строке, они могут только включить параметр или задать значение: false не отключит то, что включено в проекте. Их имена совпадают с именами параметров командной строки, с подчёркиваниями или в camelCase, а вместо значений через запятую можно передавать списки:

vim.lsp.config("djlint", {
settings = { djlint = { profile = "django", ignore = { "H013", "H016" } } },
})

Сервер запрашивает раздел djlint через workspace/configuration. Редактор, который не умеет на это отвечать, может передать те же ключи в initializationOptions.

У двух настроек нет соответствующего параметра командной строки:

  • use_editor_indentation: форматировать с размером табуляции из редактора, а не с indent.
  • python_rules: установите false, чтобы пропускать пользовательские правила с python_module; так код проекта не будет запускаться.

djLint берёт profile из первого источника, где он задан:

  1. Настройки редактора.
  2. Конфигурация проекта.
  3. Язык документа: например, для htmldjango используется профиль django.

Если профиль нигде не задан, djLint работает без профиля, как и в командной строке. Проще всего задать profile в конфигурации проекта: это работает в любом редакторе, и не нужно настраивать идентификатор языка.

  • Замечания появляются после короткой паузы в наборе. Редактор, поддерживающий pull-диагностику, запрашивает их сам, а любому другому сервер присылает их.
  • exclude, extend_exclude и use_gitignore действуют и на открытые документы. У исключённого документа нет замечаний, и он не форматируется.
  • Сервер перечитывает конфигурацию при изменении pyproject.toml, djlint.toml, .djlint.toml, .djlintrc, .djlint_rules.yaml, .editorconfig или .gitignore, если редактор умеет отслеживать файлы, а иначе — при открытии или сохранении документа. Файлы, указанные в configuration или rules, перечитываются при открытии или сохранении документа. После изменения кода в python_module пользовательского правила нужен перезапуск.
  • Медленное правило задерживает всё, что идёт после него, потому что сервер выполняет задачи по одной.

В рабочем процессе GitHub Actions djLint выводит каждое замечание как аннотацию, поэтому оно отображается прямо среди изменений пул-реквеста. Настраивать ничего не нужно: djLint сам распознаёт рабочий процесс и переключает формат вывода.

- run: pip install djlint
- run: djlint . --lint --profile django

Чтобы вместо этого получить обычный консольный вывод, используйте --no-github-output, а чтобы принудительно выводить аннотации вне Actions — --github-output.

Аннотации относятся к одному пул-реквесту. Чтобы хранить замечания на вкладке Security репозитория, с историей по всем запускам, запишите их в формате SARIF и загрузите файл:

- run: djlint . --lint --sarif > djlint.sarif
continue-on-error: true
- uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: djlint.sarif

Шагу загрузки нужно разрешение security-events: write на уровне задания или рабочего процесса.

--sarif выводит в stdout документ SARIF 2.1.0 и больше ничего, поэтому вывод можно перенаправить, как показано выше. Каждое включённое правило перечисляется со ссылкой на свою документацию, у каждого замечания указаны строка и столбец, а с --check файл, который был бы переформатирован, попадает в отчёт под правилом formatting.

djLint можно использовать как хук pre-commit и для проверки, и для форматирования.

У каждого из этих профилей есть хук для проверки (хуки перечислены ниже) и хук для форматирования с тем же именем, но с reformat: djlint-reformat-django для djlint-django. Хуки задают --profile и файлы, которые передаёт pre-commit. У angular своих хуков нет: добавьте args: [--profile=angular] к djlint или djlint-reformat.

Хук Профиль Файлы
djlint нет .html, .htm, .xhtml
djlint-django django .html, .htm, .xhtml
djlint-jinja jinja .j2, .jinja, .jinja2
djlint-nunjucks nunjucks .njk
djlint-handlebars handlebars .hbs, .handlebars, .mustache
djlint-liquid liquid .html, .htm, .xhtml, .liquid
djlint-golang golang .gotmpl
djlint-tera tera .html, .htm, .xhtml
djlint-askama askama .html, .htm, .xhtml
djlint-mako mako .html, .htm, .xhtml

Для шаблонов с другими расширениями переопределите files в своей конфигурации, а если хук задаёт types_or, то и его, потому что pre-commit требует, чтобы совпадали оба. Подробнее в документации pre-commit.

repos:
- repo: https://github.com/djlint/djLint
rev: v1.54.0
hooks:
- id: djlint-reformat-django
- id: djlint-django
repos:
- repo: https://github.com/djlint/djLint
rev: v1.54.0
hooks:
- id: djlint-reformat-handlebars
files: "\\.html"
types_or: ["html"]
- id: djlint-handlebars
files: "\\.html"
types_or: ["html"]

С помощью параметров files или exclude можно ограничить каждый хук своим каталогом и так поддерживать несколько языков шаблонов в одном репозитории.

MegaLinter включает djLint. Чтобы настроить его, выполните npx mega-linter-runner --install, а параметры описаны на странице djLint в документации MegaLinter.