From a64164578724140c876f964ec17b56e8b89a6e1a Mon Sep 17 00:00:00 2001
From: confarg <280620574+confarg@users.noreply.github.com>
Date: Tue, 2 Jun 2026 22:59:30 +0200
Subject: [PATCH] feat: Allow directives on commented console blocks

---
 README.md                              | 29 +++++++++++++++++++++
 src/pytest_markdown_console/parsing.py | 17 ++++++++++--
 tests/test_parsing.py                  | 36 ++++++++++++++++++++++++++
 3 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index bd8bcde..b2ac4d5 100644
--- a/README.md
+++ b/README.md
@@ -179,6 +179,35 @@ Done.
 `yield` fixtures work normally — teardown runs after the block completes.
 
 
+### Hidden blocks
+
+Wrapping a fence in an HTML comment hides it from rendered output (e.g. on GitHub) while
+the plugin still finds and runs it. This is useful for setup steps that would clutter the
+documentation:
+
+````markdown
+<!-- pytest-markdown-console: notest -->
+<!--
+```console
+$ mkdir -p tmp
+```
+-->
+````
+
+To attach a directive to a hidden block, place it on the line immediately before the `<!--`
+opener:
+
+````markdown
+<!-- pytest-markdown-console: cwd:tmp -->
+<!--
+```console
+$ echo hi
+hi
+```
+-->
+````
+
+
 ### Exclude a block from testing
 
 To exclude a block from being collected as a test at all, use the `notest` directive:
diff --git a/src/pytest_markdown_console/parsing.py b/src/pytest_markdown_console/parsing.py
index aa6b2ce..9882bb9 100644
--- a/src/pytest_markdown_console/parsing.py
+++ b/src/pytest_markdown_console/parsing.py
@@ -8,6 +8,7 @@
 
 _FENCE_OPEN = re.compile(r"^```\s*console\b", re.IGNORECASE)
 _FENCE_CLOSE = re.compile(r"^```\s*$")
+_HTML_COMMENT_OPEN = re.compile(r"^\s*<!--\s*$")
 
 
 def _comment_start(cmd: str) -> int | None:
@@ -97,6 +98,19 @@ def _handle_dollar_line(
     ), False
 
 
+def _find_block_directive(
+    lines: list[str],
+    lineno: int,
+    directive_re: re.Pattern[str],
+) -> re.Match[str] | None:
+    """Return the directive match for the fence at *lineno*, looking through a bare <!-- if needed."""
+    prev_line = lines[lineno - 2] if lineno >= 2 else ""  # noqa: PLR2004
+    m = directive_re.match(prev_line)
+    if m is None and lineno >= 3 and _HTML_COMMENT_OPEN.match(prev_line):  # noqa: PLR2004
+        m = directive_re.match(lines[lineno - 3])
+    return m
+
+
 def _parse_file_config(
     lines: list[str],
     directive_tag: str,
@@ -128,8 +142,7 @@ def parse_blocks(source: str, directive: str = "pytest-markdown-console") -> lis
             if _FENCE_OPEN.match(stripped):
                 indent = raw[: len(raw) - len(stripped)]
                 in_block = True
-                prev_line = lines[lineno - 2] if lineno >= 2 else ""  # noqa: PLR2004
-                directive_match = directive_re.match(prev_line)
+                directive_match = _find_block_directive(lines, lineno, directive_re)
                 tokens_str = directive_match.group(1) if directive_match else ""
                 notest, cwd_override, only, skip, shell, fixtures = _parse_directive_tokens(tokens_str)
                 current_block = ConsoleBlock(
diff --git a/tests/test_parsing.py b/tests/test_parsing.py
index fbc813f..05c60bb 100644
--- a/tests/test_parsing.py
+++ b/tests/test_parsing.py
@@ -434,3 +434,39 @@ def test_file_directive_no_effect_without_suffix():
     # so the block should get no shell from either source.
     block = parse_blocks(source)[0]
     assert block.shell is None
+
+
+# ---------------------------------------------------------------------------
+# Directives on HTML-comment-wrapped (hidden) blocks
+# ---------------------------------------------------------------------------
+
+
+def test_directive_through_html_comment_opener():
+    """A directive on the line before a bare <!-- is applied to the following fence."""
+    source = "<!-- pytest-markdown-console: notest -->\n<!--\n```console\n$ echo hi\n```\n-->\n"
+    block = parse_blocks(source)[0]
+    assert block.notest is True
+
+
+def test_bare_html_comment_opener_no_directive():
+    """A bare <!-- before the fence with no preceding directive leaves the block with defaults."""
+    source = "<!--\n```console\n$ echo hi\n```\n-->\n"
+    block = parse_blocks(source)[0]
+    assert block.notest is False
+    assert block.cwd_override is None
+    assert block.shell is None
+
+
+def test_directive_through_html_comment_opener_indented():
+    """A directive + bare <!-- before an indented fence inside a list item is applied."""
+    source = (
+        "- item\n\n"
+        "    <!-- pytest-markdown-console: notest -->\n"
+        "    <!--\n"
+        "    ```console\n"
+        "    $ echo hi\n"
+        "    ```\n"
+        "    -->\n"
+    )
+    block = parse_blocks(source)[0]
+    assert block.notest is True