Ir al contenido

Configuración

La configuración va en el pyproject.toml de tu proyecto, en un djlint.toml o .djlint.toml, o en un .djlintrc. Las opciones de la línea de comandos prevalecen sobre el archivo de configuración, pero una opción solo puede activar algo, así que no puede desactivar un interruptor que activa el archivo de configuración. Los ajustes del proyecto prevalecen sobre un archivo de configuración global indicado con --configuration, salvo que se use --prefer-configuration.

djLint busca estos archivos hacia arriba a partir de la primera ruta que revisa (con -, desde la carpeta de --stdin-filename, o desde el directorio actual si no se indica). Se detiene en la primera carpeta que contiene un djlint.toml, un .djlint.toml, un .djlintrc, un .djlint_rules.yaml o un pyproject.toml con [tool.djlint], y nunca pasa de la raíz de un repositorio (una carpeta con una carpeta o un archivo .git, o una carpeta .hg). Un pyproject.toml sin ajustes de djLint no la detiene, así que un paquete de un monorepo con su propio pyproject.toml recibe los ajustes del repositorio. djLint solo lee la carpeta donde se detiene: [tool.djlint] en su pyproject.toml si esa tabla define algo; si no, su djlint.toml o .djlint.toml; si no, su .djlintrc, y avisa de los que hay ahí y no lee.

Cuando ni la línea de comandos ni la configuración fijan indent o max_line_length, djLint toma indent_size o max_line_length de los archivos .editorconfig, como hacen los editores: cada archivo los recibe según su propia ruta, gana el .editorconfig más cercano y los de más arriba completan lo que falta, hasta uno con root = true o la raíz del proyecto.

El formato de pyproject.toml es toml.

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

El formato de djlint.toml y .djlint.toml es toml.

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

El formato de .djlintrc es json.

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

Las opciones con varios valores, como ignore, aceptan una lista. También vale una cadena separada por comas, como "H014,H015", que es lo que necesita djLint antes de la 1.41.

Desde la versión 1.51, djLint avisa de un ajuste o un código de regla que no conoce y propone el más parecido que sí conoce.

allow_empty_input

desde 1.44.0 formatter linter --allow-empty-input

Valor predeterminado: false

Sale con 0 en lugar de 2 cuando las rutas indicadas no coinciden con ningún archivo. Los archivos que se encontraron y luego se omitieron por exclude, extend_exclude, use_gitignore o require_pragma ya salen con 0.

allow_empty_input=true

blank_line_after_tag

desde 0.4.2 formatter --blank-line-after-tag

Valor predeterminado: ninguno

Etiquetas de plantilla tras las que se añade una línea en blanco, como load y extends. Un grupo de ellas seguidas recibe una después de la última, y nunca se añade al final de un bloque.

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

blank_line_before_tag

desde 1.8.0 formatter --blank-line-before-tag

Valor predeterminado: ninguno

Etiquetas de plantilla antes de las que se añade una línea en blanco, como load y extends. Un grupo de ellas seguidas recibe una antes de la primera, y nunca se añade al principio de un archivo o de un bloque.

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

close_void_tags

desde 1.26.0 formatter linter --close-void-tags

Valor predeterminado: false

Cierra con una barra las etiquetas vacías conocidas, de modo que <img> se convierte en <img />. H018, que pide lo contrario, no se notifica con esta opción.

close_void_tags=true

configuration

desde 1.13.0 formatter linter --configuration

Un archivo de configuración global, un pyproject.toml, djlint.toml o .djlintrc, como uno en tu carpeta personal. El propio archivo de configuración del proyecto gana cuando ambos definen una opción, salvo que prefer_configuration esté activado.

Ventana de terminal
--configuration ~/.djlintrc

custom_blocks

desde 0.3.5 formatter --custom-blocks

Valor predeterminado: ninguno

Nombres de los bloques de plantilla personalizados que se indentan, por ejemplo toc para {% toc %}...{% endtoc %}.

custom_blocks=["toc", "example"]

custom_html

desde 0.7.0 formatter --custom-html

Valor predeterminado: ninguno

Nombres de las etiquetas HTML personalizadas que se indentan, por ejemplo mjml o simple-greeting. Un nombre puede ser una expresión regular, como mj-\w+.

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

exclude

desde 0.4.0 linter formatter --exclude

Valor predeterminado: "__pypackages__,_build,_site,.bzr,.direnv,.eggs,.git,.git-rewrite,.hg,.nox,.svn,.tox,.venv,build,dist,htmlcov,node_modules,site-packages,venv"

Rutas que se omiten, en lugar de la lista por defecto. Cada entrada es una expresión regular que se compara con nombres completos de carpetas o archivos en la ruta relativa a la raíz del proyecto o a la carpeta que se revisa, como vendor o templates/legacy, así que *.min.html se escribe .*\.min\.html.

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

extend_exclude

desde 0.4.0 linter formatter --extend-exclude

Valor predeterminado: ninguno

Rutas que se omiten además de exclude, o de la lista por defecto si exclude no está definido, como expresiones regulares iguales a las de exclude.

extend_exclude=[".custom"]

extension

desde 0.0.5 linter formatter --extension

Valor predeterminado: "html"

Extensión de los archivos que se buscan en las carpetas. Admite una sola extensión; un archivo indicado por su nombre se comprueba sea cual sea su extensión.

extension="html.dj"

files

desde 1.14.0 linter formatter

Valor predeterminado: ninguno

Rutas que se comprueban en lugar de las de la línea de comandos, en cuyo caso la línea de comandos debe llevar -, como para stdin. Con --stdin-filename, - significa stdin en cualquier caso.

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

format_attribute_js_json

desde 1.37.0 formatter --format-attribute-js-json

Valor predeterminado: false

Formatea también el JavaScript y el JSON de atributos como onclick y x-data, los que indica format_attribute_js_json_pattern. Un objeto con menos propiedades que format_attribute_js_json_min_props se queda en una sola línea.

format_attribute_js_json=true

format_attribute_js_json_min_props

desde 1.37.0 formatter --format-attribute-js-json-min-props

Valor predeterminado: 2

Formatea un objeto solo si tiene al menos este número de propiedades. Uno con menos se queda en una sola línea.

format_attribute_js_json_min_props=3

format_attribute_js_json_pattern

desde 1.37.0 formatter --format-attribute-js-json-pattern

Valor predeterminado: "^(?: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))$"

Expresión regular para los nombres de los atributos que se formatean como JavaScript o JSON. La expresión por defecto abarca los manejadores de eventos on* y los bindings de Alpine, Vue, Angular y Aurelia.

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

format_attribute_template_tags

desde 0.6.7 formatter --format-attribute-template-tags

Valor predeterminado: false

Formatea la sintaxis de plantilla dentro de los atributos de las etiquetas.

format_attribute_template_tags=true

format_css

desde 1.9.0 formatter --format-css

Valor predeterminado: false

Formatea también el contenido de las etiquetas <style>, con css-beautify. La sintaxis de plantilla dentro de ellas no es totalmente compatible.

indent_size en la tabla css, o --indent-css en la línea de comandos, define la indentación dentro de las etiquetas <style>, 4 por defecto. La tabla también admite las demás opciones de css-beautify.

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

format_js

desde 1.9.0 formatter --format-js

Valor predeterminado: false

Formatea también el JavaScript y el JSON de las etiquetas <script>, con js-beautify. Un script cuyo type no es JavaScript ni JSON, como una plantilla del lado del cliente en text/template, se deja tal cual. La sintaxis de plantilla dentro de ellas no es totalmente compatible.

indent_size en la tabla js, o --indent-js en la línea de comandos, define la indentación dentro de las etiquetas <script>, 4 por defecto. La tabla también admite las demás opciones de js-beautify.

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

github_output

desde 1.37.0 formatter linter --github-output

Valor predeterminado: ninguno

Imprime los resultados como anotaciones de GitHub Actions. Está activado por defecto dentro de GitHub Actions, y --no-github-output lo desactiva. Consulta GitHub Actions.

Ventana de terminal
--github-output

ignore

desde 0.1.5 linter --ignore

Valor predeterminado: ninguno

Códigos del linter que se omiten.

ignore=["H014", "H015"]

ignore_blocks

desde 1.24.0 formatter --ignore-blocks

Valor predeterminado: ninguno

Bloques de plantilla que no añaden indentación a su contenido. Sus hijos se tratan como hermanos del bloque y se indentan en consecuencia.

ignore_blocks=["raw", "example"]

ignore_case

desde 1.23.0 formatter linter --ignore-case

Valor predeterminado: false

No corrige las mayúsculas y minúsculas de las etiquetas HTML conocidas. H009 y H010 no se notifican con esta opción.

[tool.djlint]
ignore_case=true

include

desde 1.20.0 linter --include

Valor predeterminado: ninguno

Códigos del linter que se activan, aunque estén desactivados por defecto o el perfil los deje fuera.

include=["H014", "H015"]

indent

desde 0.3.5 formatter --indent

Valor predeterminado: 4

Espacios por nivel de indentación. Si no se define, djLint toma el indent_size que .editorconfig asigna al archivo, si lo hay.

indent=3

keep_br_inline

desde 1.45.0 formatter --keep-br-inline

Valor predeterminado: false

Mantiene <br> en la línea del texto que corta, en lugar de darle una línea propia. <hr>, que se renderiza como una línea horizontal bajo el contenido anterior, no se ve afectado.

keep_br_inline=true

line_break_after_multiline_tag

desde 1.27.0 formatter --line-break-after-multiline-tag

Valor predeterminado: false

Cuando los atributos de una etiqueta ocupan varias líneas, empieza su contenido en una línea nueva.

line_break_after_multiline_tag=true

linter_output_format

desde 0.6.7 linter --linter-output-format

Valor predeterminado: "{code} {line} {message} {match}"

El formato de cada mensaje del linter, a partir de {filename}, {line}, {end}, {code}, {message} y {match}. Sin {filename}, la salida se agrupa por archivo y cada grupo lleva una cabecera.

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

max_attribute_length

desde 0.5.8 formatter --max-attribute-length

Valor predeterminado: 70

Cuando los atributos de una etiqueta superan esta longitud, el formateador los reparte en varias líneas.

max_attribute_length=10

max_blank_lines

desde 1.31.0 formatter --max-blank-lines

Valor predeterminado: 0

Conserva como máximo este número de líneas en blanco seguidas, así que 0 las elimina. No tiene efecto con preserve_blank_lines.

max_blank_lines=5

max_line_length

desde 0.5.7 formatter --max-line-length

Valor predeterminado: 120

El formateador junta algunas etiquetas HTML y de plantilla en una sola línea solo si la línea cabe en esta longitud. Si no se define, djLint toma el max_line_length que .editorconfig asigna al archivo, si lo hay.

max_line_length=100

name_endblocks

desde 1.45.0 formatter --name-endblocks

Valor predeterminado: false

Escribe el nombre del bloque en el {% endblock %} que lo cierra, cuando el bloque ocupa varias líneas. Es lo que pide T003.

name_endblocks=true

no_entity_formatting

desde 1.45.0 formatter --no-entity-formatting

Valor predeterminado: false

No reescribe una referencia de entidad como el carácter que nombra, así que &copy; se deja tal como está escrito en lugar de convertirse en ©. Las entidades con función sintáctica, y las invisibles, nunca se reescriben en ningún caso. H023 sigue notificando las entidades con esta opción; añade H023 a ignore para conservarlas.

no_entity_formatting=true

no_function_formatting

desde 1.30.2 formatter --no-function-formatting

Valor predeterminado: false

No formatea los argumentos de las llamadas a funciones dentro de {{ }}.

no_function_formatting=true

no_indent_inner_html

desde 1.45.0 formatter --no-indent-inner-html

Valor predeterminado: false

No indenta <head> ni <body> dentro de <html>, que es como el formateador HTML integrado de VS Code organiza un documento.

no_indent_inner_html=true

no_line_after_yaml

desde 1.29.0 formatter --no-line-after-yaml

Valor predeterminado: false

No añade una línea en blanco después del front matter de YAML.

no_line_after_yaml=true

no_set_formatting

desde 1.30.2 formatter --no-set-formatting

Valor predeterminado: false

No formatea el contenido de las etiquetas {% set %}.

no_set_formatting=true

per_file_ignores

desde 1.7.0 linter --per-file-ignores

Valor predeterminado: ninguno

Códigos del linter que se omiten en los archivos cuya ruta coincide con una expresión regular. En un archivo de configuración, la clave es per-file-ignores, con guiones.

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

prefer_configuration

desde 1.45.0 formatter linter --prefer-configuration

Valor predeterminado: false

Hace que el archivo indicado por --configuration prevalezca sobre el propio archivo de configuración del proyecto, que gana por defecto cuando ambos definen la misma opción. Solo en la línea de comandos, ya que decide cómo se leen los propios archivos de configuración.

Ventana de terminal
--prefer-configuration

preserve_blank_lines

desde 1.3.0 formatter --preserve-blank-lines

Valor predeterminado: false

Conserva las líneas en blanco cuando es posible. Útil para plantillas que no son HTML, donde las líneas en blanco son intencionadas.

preserve_blank_lines=true

preserve_class_newlines

desde 1.39.0 formatter --preserve-class-newlines

Valor predeterminado: false

Conserva los saltos de línea de los atributos class escritos en varias líneas.

preserve_class_newlines=true

preserve_leading_space

desde 1.2.0 formatter --preserve-leading-space

Valor predeterminado: false

Conserva los espacios iniciales de las líneas de texto cuando es posible. Útil para plantillas que no son HTML, donde la sangría del texto es intencionada.

preserve_leading_space=true

profile

desde 0.4.5 linter formatter --profile

Valor predeterminado: ninguno

El lenguaje de plantillas. Decide qué reglas del linter se ejecutan y cómo se formatea la sintaxis de plantillas: en handlebars, por ejemplo, no hay espacios dentro de las etiquetas {{#if}}.

Sin perfil, djLint formatea la sintaxis de todos los lenguajes de plantillas, como hace all, y el linter usa las reglas de html.

Opciones:

  • html
  • django
  • jinja
  • nunjucks (para nunjucks y twig)
  • handlebars (para handlebars y mustache)
  • liquid (shopify, jekyll, eleventy)
  • golang (plantillas de go; hugo, helm)
  • angular
  • tera (también para zola; usa jinja para minijinja)
  • askama (plantillas de estilo jinja en rust; las expresiones de rust nunca se reformatean)
  • mako (las líneas de control y los comentarios ## se dejan tal cual)
  • all (todos los lenguajes de plantillas a la vez)
profile="django"

quiet

desde 0.0.9 formatter linter --quiet

Valor predeterminado: false

No imprime los diffs, la barra de progreso ni el resumen.

quiet=true

quote_style

desde 1.45.0 formatter linter --quote-style

Valor predeterminado: "double"

Comillas que se usan en las cadenas dentro de las etiquetas de plantilla: double o single. T002 pide las mismas comillas, y el formateador las usa en condiciones como {% if x == "a" %}, para que un mismo archivo no escriba la misma cadena de dos formas. El entrecomillado de los atributos HTML se deja a H008.

quote_style="single"

require_pragma

desde 0.5.8 formatter linter --require-pragma

Valor predeterminado: false

Solo formatea o analiza los archivos que empiezan con un comentario djlint:on. Puede ser un comentario HTML o uno del lenguaje de plantillas indicado en profile y, sin perfil, uno de cualquiera de ellos.

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

rules

desde 1.41.0 formatter linter --rules

Un archivo de reglas personalizadas en el formato de .djlint_rules.yaml, que se lee en lugar del de la raíz del proyecto.

Ventana de terminal
--rules ../shared/.djlint_rules.yaml

sarif

desde 1.46.0 formatter linter --sarif

Valor predeterminado: false

Imprime los problemas como un documento SARIF 2.1.0, para el escaneo de código de GitHub y otras herramientas. Consulta GitHub Actions.

Ventana de terminal
--sarif

single_attribute_per_line

desde 1.40.0 formatter --single-attribute-per-line

Valor predeterminado: false

Cuando una etiqueta de apertura se parte en varias líneas, pone el nombre de la etiqueta, cada atributo y el corchete angular de cierre en líneas separadas.

single_attribute_per_line=true

sort_attributes

desde 1.45.0 formatter --sort-attributes

Valor predeterminado: false

Ordena los atributos por nombre, con id primero y class segundo. Una etiqueta cuyos atributos están condicionados por una etiqueta de plantilla conserva el orden en que se escribió, ya que sacar un atributo de su rama cambiaría la página.

sort_attributes=true

sort_load_tags

desde 1.47.0 formatter --sort-load-tags

Valor predeterminado: false

Ordena las bibliotecas de las etiquetas {% load %} y quita las que están escritas dos veces, de modo que {% load static i18n %} se convierte en {% load i18n static %}. En {% load a b from library %} se ordenan los nombres que van antes de from. Cuando dos bibliotecas definen una etiqueta o un filtro con el mismo nombre, prevalece la que se carga en último lugar, así que ordenarlas puede cambiar cuál usa la plantilla.

sort_load_tags=true

statistics

desde 1.16.0 linter --statistics

Valor predeterminado: false

Después del análisis, imprime cuántas veces se encontró cada código.

Ventana de terminal
--statistics

stdin_filename

desde 1.43.0 formatter linter --stdin-filename

Valor predeterminado: "-"

Ruta que representa a stdin en los mensajes y al comparar con exclude y per-file-ignores.

Ventana de terminal
--stdin-filename templates/index.html

use_gitignore

desde 0.5.9 linter formatter --use-gitignore

Valor predeterminado: false

Omite también las rutas que indica el .gitignore de la raíz del proyecto.

use_gitignore=true

version

desde 0.3.9 formatter linter --version

Muestra la versión y sale.

Ventana de terminal
--version

warn

desde 0.7.6 formatter linter --warn

Valor predeterminado: false

Sale con 0 en lugar de 1 cuando hay errores del linter o archivos por reformatear.

Ventana de terminal
--warn