集成
djLint 已有多种编辑器集成。
无论使用哪种编辑器,都请把 djLint 安装在编辑器能找到的位置,最好是项目的虚拟环境中,然后从该环境启动编辑器,或者让编辑器指向该环境中的 djlint。这样,编辑器运行的就是项目锁定的版本,结果与 pre-commit 钩子或 CI 中的一致。
Visual Studio Code
安装 djLint 扩展;如果使用 VSCodium,则安装 Open VSX 上的版本。它会在你的环境中查找 djLint,找不到时回退到内置的 djLint;如果你的 djLint 支持语言服务器,它就会使用语言服务器。
其代码托管在 GitHub 上。
Neovim
在 Neovim 中,djLint 既可以用作代码检查工具,也可以用作格式化工具。
内置 LSP 客户端(推荐)
Neovim 0.11 及更高版本可以直接与 djLint 的语言服务器通信,无需任何插件。这样可以在输入时得到检查结果,并带有下划线标出的范围,还能用 vim.lsp.buf.format() 格式化:
vim.lsp.config("djlint", {
cmd = { "djlint", "--lsp" },
filetypes = { "html", "htmldjango", "jinja", "jinja.html", "handlebars", "liquid", "gotmpl" },
root_markers = { "pyproject.toml", "djlint.toml", ".djlint.toml", ".djlintrc", ".git" },
})
vim.lsp.enable("djlint")
要在保存时格式化,请在同一配置中添加以下内容:
vim.api.nvim_create_autocmd("BufWritePre", {
pattern = {
"*.html", "*.jinja", "*.jinja2", "*.j2",
"*.hbs", "*.handlebars", "*.liquid", "*.gotmpl",
},
callback = function(args)
vim.lsp.buf.format({ bufnr = args.buf, name = "djlint" })
end,
})
请参阅设置。
conform.nvim 和 nvim-lint
conform.nvim 负责格式化,nvim-lint 负责代码检查,两者都以命令的形式运行 djLint。检查结果没有下划线标出的范围,并且只有在你让 nvim-lint 执行检查时才会出现。
require("conform").setup({ formatters_by_ft = { htmldjango = { "djlint" } } })
require("lint").linters_by_ft = { htmldjango = { "djlint" } }
none-ls
efm-langserver
- 通过 Mason 使用
:MasonInstall efm djlint安装 efm-langserver 和 djLint - 将
htmldjango添加到filetypes中。 - 创建格式化配置:
local djlint = {
formatCommand = "djlint --reformat --quiet --warn -",
formatStdin = true,
}
- 通过
htmldjango = { djlint }将语言与格式化工具关联起来。
配置示例:
local djlint = {
formatCommand = "djlint --reformat --quiet --warn -",
formatStdin = true,
}
require("lspconfig").efm.setup({
filetypes = { "htmldjango" },
init_options = { documentFormatting = true },
settings = {
rootMarkers = { ".git/" },
languages = {
htmldjango = { djlint },
},
},
})
coc.nvim
JetBrains IDE
在 PyCharm 以及其他基于 IntelliJ 的 IDE 中,请使用免费的 LSP4IJ 插件:
- 从 Marketplace 安装 LSP4IJ。
- 打开 LSP Consoles 工具窗口,添加一个新的语言服务器。
- 在 Server 选项卡中,将名称设为
djLint,将命令设为djlint --lsp;如果它不在 PATH 中,请使用项目虚拟环境中djlint的完整路径。 - 在 Mappings 选项卡中,为你的模板添加文件名模式,例如
*.html。如果项目的配置中没有设置预设,对于 Django 项目,请将语言 ID 设为htmldjango,以便选中正确的预设。 - 在 Configuration 选项卡中,可以以 JSON 格式在
djlint键下填写设置。
检查结果会显示在编辑器中,并且 Reformat Code 可以对已映射的文件使用该服务器。
Sublime Text
LSP(推荐)
LSP 包会运行语言服务器,从而在输入时提供检查结果,并支持格式化。
运行 Preferences: LSP Server Configurations 并添加:
{ "djlint": { "enabled": true, "command": ["djlint", "--lsp"], "selector": "text.html" } }
SublimeLinter
djLint 可以用作 Sublime Text 的 Linter 插件,可通过 package-control 安装。
cmd + shift + p- 安装 SublimeLinter
- 安装 SublimeLinter-contrib-djlint
请确保 djLint 安装在全局 Python 中,或者位于 PATH 上。
Helix
Helix 可以通过 languages.toml 运行语言服务器:
[language-server.djlint]
command = "djlint"
args = ["--lsp"]
[[language]]
name = "html"
language-servers = ["djlint", "vscode-html-language-server"]
Emacs
使用 Emacs 29 及更高版本自带的 Eglot:
(with-eval-after-load 'eglot
(add-to-list 'eglot-server-programs
'((html-mode web-mode) . ("djlint" "--lsp"))))
然后在模板中运行 M-x eglot。eglot-format-buffer 可以格式化该模板。
语言服务器
djlint --lsp 会通过 stdio 将 djLint 作为语言服务器运行。它会持续运行,因此编辑器可以在你输入时获得检查结果,格式化文档时也无需每次都启动一个进程。
它会报告检查结果,并能格式化整个文档。它不需要额外的包。任何支持 LSP 的编辑器都可以用同一条命令运行它。
设置
服务器读取项目配置的方式与命令行相同:从每个文件所在的文件夹开始向上查找。编辑器中的设置优先于项目配置,但与命令行一样,它们只能开启某个选项或设置某个值:false 无法关闭项目中开启的选项。设置使用命令行选项的名称,可以写成下划线形式或 camelCase 形式;以逗号分隔的值可以写成列表:
vim.lsp.config("djlint", {
settings = { djlint = { profile = "django", ignore = { "H013", "H016" } } },
})
服务器通过 workspace/configuration 请求 djlint 部分。无法响应该请求的编辑器,可以在 initializationOptions 中发送相同的键。
有两项设置没有对应的命令行选项:
use_editor_indentation:使用编辑器的制表符大小进行格式化,而不是使用indent。python_rules:设为false可跳过带有python_module的自定义规则,从而避免运行项目中的代码。
djLint 会从以下来源中第一个设置了 profile 的来源获取它:
- 编辑器的设置。
- 项目的配置。
- 文档的语言:例如,
htmldjango会使用django预设。
如果以上都没有设置,它会像在命令行中一样,不使用任何预设运行。在项目配置中设置 profile 是最简单的做法:它在所有编辑器中都有效,也无需设置语言 ID。
工作方式
- 检查结果会在你停止输入片刻后出现。支持拉取诊断(pull diagnostics)的编辑器会主动请求结果,其他编辑器则由服务器推送。
exclude、extend_exclude和use_gitignore对已打开的文档同样生效。被排除的文档不会有检查结果,也不会被格式化。- 当
pyproject.toml、djlint.toml、.djlint.toml、.djlintrc、.djlint_rules.yaml、.editorconfig或.gitignore发生变化时,如果编辑器能够监视文件,服务器就会重新加载配置;否则会在打开或保存文档时重新加载。configuration或rules指定的文件会在打开或保存文档时重新读取。修改自定义规则的python_module代码后,需要重启服务器。 - 运行缓慢的规则会拖慢其后的处理,因为服务器一次只做一件事。
GitHub Actions
在 GitHub Actions 工作流中,djLint 会把每条检查结果报告为一个注解(annotation),使其以内联方式显示在拉取请求的差异中。无需任何配置:djLint 会检测到工作流并自动切换输出方式。
- run: pip install djlint
- run: djlint . --lint --profile django
使用 --no-github-output 可以改为输出普通的控制台格式,使用 --github-output 则可以在 Actions 之外强制输出注解。
注解只属于某一个拉取请求。如果想把检查结果保留在仓库的 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 规则下报告。Azure DevOps、GitLab 以及大多数编辑器都能读取这种格式。
Pre-Commit
djLint 可以用作 pre-commit 钩子,既能做代码检查,也能做格式化。
该仓库为特定的 djLint 预设提供了多个预先配置好的钩子(它们只是预先设置了 --profile 参数,并告诉 pre-commit 要查找哪些文件扩展名):
djlint用于代码检查,djlint-reformat用于格式化
查找匹配*.html的文件,不设置--profile。djlint-django和djlint-reformat-django
查找匹配*.html的文件,并设置--profile=django。djlint-jinja和djlint-reformat-jinja
查找匹配*.j2、*.jinja或*.jinja2的文件,并设置--profile=jinja。djlint-nunjucks和djlint-reformat-nunjucks
查找匹配*.njk的文件,并设置--profile=nunjucks。djlint-handlebars和djlint-reformat-handlebars
查找匹配*.hbs的文件,并设置--profile=handlebars。djlint-liquid和djlint-reformat-liquid
查找匹配*.html的文件,并设置--profile=liquid。djlint-golang和djlint-reformat-golang
查找匹配*.gotmpl的文件,并设置--profile=golang。djlint-tera和djlint-reformat-tera
查找匹配*.html的文件,并设置--profile=tera。djlint-askama和djlint-reformat-askama
查找匹配*.html的文件,并设置--profile=askama。djlint-mako和djlint-reformat-mako
查找匹配*.html的文件,并设置--profile=mako。
请注意,这些预定义钩子接受的输入有时过于保守(你的模板可能使用了不同的扩展名),因此 pre-commit 明确允许你覆盖其中任何预定义选项。更多配置请参阅 pre-commit 文档。
默认 Django 示例
repos:
- repo: https://github.com/djlint/djLint
rev: v1.50.4
hooks:
- id: djlint-reformat-django
- id: djlint-django
使用 .html 而非 .hbs 扩展名的 Handlebars
repos:
- repo: https://github.com/djlint/djLint
rev: v1.50.4
hooks:
- id: djlint-reformat-handlebars
files: "\\.html"
types_or: ["html"]
- id: djlint-handlebars
files: "\\.html"
types_or: ["html"]
可以使用 files 或 exclude 参数把每个钩子限定在各自的目录中,从而在同一个仓库中支持多种模板语言。
MegaLinter
djlint 已原生内置于 MegaLinter 的 100 多个代码检查工具之中
要安装它,只需运行 npx mega-linter-runner --install 并按照说明操作