feat: add --stdin-filename so per-file-ignores works for stdin input

Author: monosans

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 [Semantic Versioning](https://semver.org/)
 
+## [Unreleased]
+
+### Feature
+
+- New `--stdin-filename` option tells djLint the real path of content piped in on stdin (`djlint -`). Stdin previously always carried the name `-`, which no realistic `per-file-ignores` pattern matches, so per-file ignores were silently dead for piped input; the given name is now what `per-file-ignores` matches against and what linter messages report. Editor integrations that lint the open buffer through stdin get the same per-file ignores as a run over the file on disk. Path separators are normalized the same way they are for files on disk, so a Windows-style path matches a pattern written with `/`.
+
 ## [1.42.3] - 2026-07-23
 
 ### Fix

docs/src/_data/configuration.json

@@ -670,5 +670,18 @@
       },
       { "name": "cli", "value": "--format-attribute-js-json-min-props 3" }
     ]
+  },
+  {
+    "name": "stdin_filename",
+    "tags": ["formatter", "linter"],
+    "description": {
+      "en": "Filename to use for per-file-ignores and messages when reading from stdin. Defaults to \"-\".",
+      "ru": "Имя файла, используемое для per-file-ignores и сообщений при чтении из stdin. По умолчанию \"-\".",
+      "fr": "Nom de fichier à utiliser pour per-file-ignores et les messages lors de la lecture depuis stdin. La valeur par défaut est \"-\".",
+      "zh": "从标准输入（stdin）读取时，用于 per-file-ignores 及消息中的文件名。默认值为 \"-\"。"
+    },
+    "usage": [
+      { "name": "cli", "value": "--stdin-filename templates/index.html" }
+    ]
   }
 ]

docs/src/_includes/cli.md

@@ -11,6 +11,9 @@ Options:
   -i, --ignore TEXT               Codes to ignore. ex: "H014,H017"
   --reformat                      Reformat the file(s).
   --check                         Check formatting on the file(s).
+  --stdin-filename TEXT           Filename to use for per-file-ignores and
+                                  messages when reading from stdin. [default:
+                                  -]
   --indent INTEGER                Indent spacing. [default: 4]
   --quiet                         Do not print diff when reformatting.
   --profile TEXT                  Enable defaults by template language. ops:

docs/src/docs/getting-started.md

@@ -83,3 +83,9 @@ Output -
 ```html
 <div></div>
 ```
+
+When reading from stdin, djLint has no real path to match against `per-file-ignores` or to show in messages, so it uses `-` by default. Pass `--stdin-filename` to tell djLint the real path of the piped content, for example when an editor integration pipes a file's contents in on save.
+
+```bash
+echo "<div></div>" | djlint - --stdin-filename templates/index.html
+```

src/djlint/__init__.py

@@ -59,6 +59,16 @@
 )
 @click.option("--reformat", is_flag=True, help="Reformat the file(s).")
 @click.option("--check", is_flag=True, help="Check formatting on the file(s).")
+@click.option(
+    "--stdin-filename",
+    type=str,
+    default=None,
+    help=(
+        "Filename to use for per-file-ignores and messages when reading"
+        " from stdin. [default: -]"
+    ),
+    show_default=False,
+)
 @click.option(
     "--indent",
     type=int,
@@ -294,6 +304,7 @@ def main(
     reformat: bool,
     indent: int | None,
     check: bool,
+    stdin_filename: str | None,
     quiet: bool,
     profile: str | None,
     require_pragma: bool,
@@ -361,6 +372,7 @@ def main(
         lint=lint or not (reformat or check),
         reformat=reformat,
         check=check,
+        stdin_filename=stdin_filename,
         use_gitignore=use_gitignore,
         warn=warn,
         preserve_leading_space=preserve_leading_space,
@@ -531,18 +543,22 @@ def process_stdin(
     output: ProcessResult = {}
     html = stdin_text
     formatted_code = None
+    stdin_filename = config.stdin_filename or "-"
 
     if config.reformat or config.check:
         from djlint.reformat import reformat_string  # noqa: PLC0415
 
         output["format_message"], formatted_code = reformat_string(
-            config, stdin_text, "-"
+            config, stdin_text, stdin_filename
         )
         html = formatted_code
 
     if config.lint:
         from djlint.lint import linter  # noqa: PLC0415
 
-        output["lint_message"] = linter(config, html, "-", "-")
+        # as lint_file() does, match per_file_ignores against a posix path
+        output["lint_message"] = linter(
+            config, html, stdin_filename, Path(stdin_filename).as_posix()
+        )
 
     return output, formatted_code

src/djlint/settings.py

@@ -1120,6 +1120,7 @@ class Config:
         "start_template_tags",
         "statistics",
         "stdin",
+        "stdin_filename",
         "tag_indent",
         "tag_unindent",
         "tag_unindent_line",
@@ -1185,6 +1186,7 @@ def __init__(
         max_blank_lines: int | None = None,
         github_output: bool = False,
         stdin: bool | None = None,
+        stdin_filename: str | None = None,
     ) -> None:
         self.project_root = find_project_root(
             Path.cwd() if src == "-" else Path(src).resolve()
@@ -1216,6 +1218,7 @@ def setting_int(key: str, default: int) -> int:
         self.warn = warn
         self.github_output = github_output
         self.statistics = statistics
+        self.stdin_filename = stdin_filename
 
         # simple options; the command line takes precedence over the config
         self.extension = str(

tests/test_config/test_stdin_filename/__init__.py

@@ -0,0 +1,4 @@
+[tool.djlint.per-file-ignores]
+"myfile.html" = "H025"
+"templates/index.html" = "H025"
+"^-$" = "H020"

tests/test_config/test_stdin_filename/pyproject.toml

@@ -0,0 +1,99 @@
+"""Djlint tests specific to --stdin-filename.
+
+run::
+
+   pytest tests/test_config/test_stdin_filename/test_config.py --cov=src/djlint \
+          --cov-branch --cov-report xml:coverage.xml --cov-report term-missing
+
+for a single test, run::
+
+   pytest tests/test_config/test_stdin_filename/test_config.py::test_stdin_filename_matches_per_file_ignores \
+     --cov=src/djlint --cov-branch --cov-report xml:coverage.xml --cov-report term-missing
+
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from djlint import main as djlint
+
+if TYPE_CHECKING:
+    from click.testing import CliRunner
+
+# the pyproject.toml in this directory has:
+#   "myfile.html"          = "H025"
+#   "templates/index.html" = "H025"
+#   "^-$"                  = "H020"
+# and the html below triggers both H025 and H020 when neither is ignored.
+_HTML = "<div>\n    <div></div>"
+_CONFIG = "tests/test_config/test_stdin_filename/pyproject.toml"
+
+
+def test_stdin_filename_matches_per_file_ignores(runner: CliRunner) -> None:
+    """A --stdin-filename matching a per-file-ignores pattern suppresses it."""
+    result = runner.invoke(
+        djlint,
+        ("-", "--stdin-filename", "myfile.html", "--configuration", _CONFIG),
+        input=_HTML,
+    )
+    assert "H025" not in result.output
+    assert "H020" in result.output
+
+
+def test_stdin_filename_not_matching_per_file_ignores(
+    runner: CliRunner,
+) -> None:
+    """A --stdin-filename that matches no pattern reports every rule."""
+    result = runner.invoke(
+        djlint,
+        ("-", "--stdin-filename", "other.html", "--configuration", _CONFIG),
+        input=_HTML,
+    )
+    assert "H025" in result.output
+    assert "H020" in result.output
+
+
+def test_stdin_filename_default_unchanged(runner: CliRunner) -> None:
+    """Without --stdin-filename, per-file-ignores still match against "-"."""
+    result = runner.invoke(
+        djlint, ("-", "--configuration", _CONFIG), input=_HTML
+    )
+    assert "H020" not in result.output
+    assert "H025" in result.output
+
+
+def test_stdin_filename_uses_native_separators(runner: CliRunner) -> None:
+    """A native-separator path matches a pattern written with "/"."""
+    result = runner.invoke(
+        djlint,
+        (
+            "-",
+            "--stdin-filename",
+            str(Path("templates", "index.html")),
+            "--configuration",
+            _CONFIG,
+        ),
+        input=_HTML,
+    )
+    assert "H025" not in result.output
+    assert "H020" in result.output
+
+
+def test_stdin_filename_used_in_lint_message(runner: CliRunner) -> None:
+    """The --stdin-filename value is used as the error dict's filename key."""
+    result = runner.invoke(
+        djlint,
+        (
+            "-",
+            "--stdin-filename",
+            "myfile.html",
+            "--configuration",
+            _CONFIG,
+            "--linter-output-format",
+            "{filename} {code}",
+        ),
+        input=_HTML,
+    )
+    assert "myfile.html H020" in result.output

tests/test_config/test_stdin_filename/test_config.py

@@ -148,6 +148,16 @@ def test_stdin(runner: CliRunner) -> None:
     assert "No files to check!" in result.output
 
 
+def test_stdin_filename_option(runner: CliRunner) -> None:
+    result = runner.invoke(
+        djlint,
+        ("-", "--stdin-filename", "custom.html"),
+        input='<div><p id="a"></p></div>',
+    )
+    assert result.exit_code == 0
+    assert "Linted 1 file" in result.output
+
+
 def test_stdin_reformat_without_temp_file(
     runner: CliRunner, monkeypatch: pytest.MonkeyPatch
 ) -> None: