diff --git a/python/tests/unit/collectors/test_references.py b/python/tests/unit/collectors/test_references.py index 2875bd1..e8e79c1 100644 --- a/python/tests/unit/collectors/test_references.py +++ b/python/tests/unit/collectors/test_references.py @@ -455,7 +455,6 @@ class TestLinkReferences: pytest.param(b"text [TOC]", id="inline"), pytest.param(b"[TOC] text", id="inline-prefix"), pytest.param(b"[TOC]\ntext", id="paragraph"), - pytest.param(b" [TOC]", id="code-block"), ], ) def test_link_ref_toc_text(self, md: bytes) -> None: @@ -737,10 +736,7 @@ class TestLinkDefinitions: def test_no_link_def_indent(self) -> None: md = b" [id]: href" refs = collect(md) - assert len(refs) == 1 - - link_refs = link_refs_only(refs) - assert len(link_refs) == 1 + assert len(refs) == 0 def test_no_link_def_prefix(self) -> None: md = b"text [id]: href" @@ -1710,6 +1706,88 @@ class TestFencedCodeBlocks: # --------------------------------------------------------------------------- +class TestSnippets: + """Tests for pymdownx.snippets markers.""" + + def test_section_markers_are_ignored(self) -> None: + md = ( + b"# --8<-- [start:reference_section]\n" + b"Text\n" + b"# --8<-- [end:reference_section]\n" + ) + refs = collect(md) + assert len(refs) == 0 + + def test_section_markers_do_not_hide_following_links(self) -> None: + md = ( + b"# --8<-- [start:reference_section]\n" + b"Text\n" + b"# --8<-- [end:reference_section]\n" + b"[after](href)\n" + ) + refs = collect(md) + assert len(refs) == 1 + + links = links_only(refs) + assert len(links) == 1 + assert text(md, links[0].text) == b"after" + assert text(md, links[0].href) == b"href" + + +# --------------------------------------------------------------------------- + + +class TestIndentedCodeBlocks: + """Tests for indented code blocks.""" + + def test_indented_code_is_ignored(self) -> None: + md = b"\n [Start][]\n" + refs = collect(md) + assert len(refs) == 0 + + def test_indented_code_with_blank_line_continuation_is_ignored( + self, + ) -> None: + md = b"\n [Start][]\n\n [End][]\n" + refs = collect(md) + assert len(refs) == 0 + + def test_indented_code_does_not_hide_following_link(self) -> None: + md = b"\n [Start][]\n\n[after](href)\n" + refs = collect(md) + assert len(refs) == 1 + + links = links_only(refs) + assert len(links) == 1 + assert text(md, links[0].text) == b"after" + assert text(md, links[0].href) == b"href" + + +# --------------------------------------------------------------------------- + + +class TestMarkdownComments: + """Tests for Markdown comments written as link-definition hacks.""" + + def test_markdown_comment_is_ignored(self) -> None: + md = b"[//]: # (comment)\n" + refs = collect(md) + assert len(refs) == 0 + + def test_markdown_comment_does_not_hide_following_link(self) -> None: + md = b"[//]: # (comment)\n[after](href)\n" + refs = collect(md) + assert len(refs) == 1 + + links = links_only(refs) + assert len(links) == 1 + assert text(md, links[0].text) == b"after" + assert text(md, links[0].href) == b"href" + + +# --------------------------------------------------------------------------- + + class TestInlineCode: """Tests for inline code.""" diff --git a/python/zensical/collectors/references/cursor.py b/python/zensical/collectors/references/cursor.py index 3738077..af25ebe 100644 --- a/python/zensical/collectors/references/cursor.py +++ b/python/zensical/collectors/references/cursor.py @@ -169,6 +169,27 @@ def _scan(cursor: Cursor) -> Iterator[Reference]: while cursor.pos < cursor.end: char = cursor.data[cursor.pos] + # Top-level indented code block. + if cursor.at_line_start(): + end = _scan_indented_code(cursor) + if end is not None: + cursor.advance(end - cursor.pos) + continue + + # Snippet directives and section markers: --8<-- ... + if cursor.at_line_start(): + end = _scan_snippet(cursor) + if end is not None: + cursor.advance(end - cursor.pos) + continue + + # Markdown comment hack: [//]: ... + if cursor.at_line_start(): + end = _scan_markdown_comment(cursor) + if end is not None: + cursor.advance(end - cursor.pos) + continue + # Escaped character or math if char == _BACKSLASH: next = cursor.peek(1) @@ -387,6 +408,98 @@ def _scan(cursor: Cursor) -> Iterator[Reference]: # --------------------------------------------------------------------------- +def _scan_indented_code(cursor: Cursor) -> int | None: + """Scan for a top-level indented code block.""" + line = _find_line_start(cursor, cursor.pos) + if not _is_previous_line_blank(cursor, line): + return None + + pos = line + indent, end = _measure_indent(cursor, pos) + if indent < 4: # noqa: PLR2004 + return None + if end >= cursor.end or cursor.data[end] in (_CR, _NL): + return None + + # Consume the whole chunk: indented lines plus blank continuation lines. + pos = _skip_line(cursor, end) + while pos < cursor.end: + if _is_blank_line(cursor, pos): + pos = _skip_line(cursor, pos) + continue + + indent, end = _measure_indent(cursor, pos) + if indent < 4: # noqa: PLR2004 + break + pos = _skip_line(cursor, end) + + return pos + + +# --------------------------------------------------------------------------- + + +def _scan_snippet(cursor: Cursor) -> int | None: + """Scan for a pymdownx.snippets directive or section marker line.""" + pos = _skip_whitespace(cursor, cursor.pos) + + # Markdown snippet sections are commonly wrapped in heading comments. + if pos < cursor.end and cursor.data[pos] == _HASH: + pos = _skip_whitespace(cursor, pos + 1) + + # Match the scissors marker: -+8<-+ + start = pos + while pos < cursor.end and cursor.data[pos] == _DASH: + pos += 1 + if pos == start or pos >= cursor.end or cursor.data[pos] != ord(b"8"): + return None + pos += 1 + + start = pos + while pos < cursor.end and cursor.data[pos] == _LANGLE: + pos += 1 + if pos == start: + return None + + start = pos + while pos < cursor.end and cursor.data[pos] == _DASH: + pos += 1 + if pos == start: + return None + + # Snippet syntax ends at the line boundary. + if pos < cursor.end and cursor.data[pos] not in (_SPACE, _TAB, _CR, _NL): + return None + + return _skip_line(cursor, pos) + + +# --------------------------------------------------------------------------- + + +def _scan_markdown_comment(cursor: Cursor) -> int | None: + """Scan for a Markdown comment line written as `[//]: ...`.""" + start = cursor.pos + + # Skip if there're more than four spaces of indentation + if cursor.col > 3: # noqa: PLR2004 + return None + + id, end = _scan_link_id(cursor, start) + if ( + id is None + or cursor.data[id.start - cursor.shift : id.end - cursor.shift] != b"//" + ): + return None + if end >= cursor.end or cursor.data[end] != _COLON: + return None + + return _skip_line(cursor, end) + + +# --------------------------------------------------------------------------- + + def _scan_link_or_link_ref(cursor: Cursor) -> Link | LinkReference | None: """Scan for link or link reference. @@ -1534,6 +1647,23 @@ def _skip_whitespace(cursor: Cursor, pos: int) -> int: return pos +def _measure_indent(cursor: Cursor, pos: int) -> tuple[int, int]: + """Return visual indentation width and first non-whitespace position.""" + indent = 0 + while pos < cursor.end: + char = cursor.data[pos] + if char == _SPACE: + indent += 1 + pos += 1 + continue + if char == _TAB: + indent += 4 - (indent % 4) + pos += 1 + continue + break + return indent, pos + + def _skip_whitespace_newline(cursor: Cursor, pos: int) -> int: """Skip trailing horizontal whitespace and at most one newline.""" pos = _skip_whitespace(cursor, pos) diff --git a/uv.lock b/uv.lock index 9d5a2e2..a493c4e 100644 --- a/uv.lock +++ b/uv.lock @@ -636,15 +636,15 @@ wheels = [ [[package]] name = "pymdown-extensions" -version = "10.21.2" +version = "10.21.3" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "markdown" }, { name = "pyyaml" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/df/08/f1c908c581fd11913da4711ea7ba32c0eee40b0190000996bb863b0c9349/pymdown_extensions-10.21.2.tar.gz", hash = "sha256:c3f55a5b8a1d0edf6699e35dcbea71d978d34ff3fa79f3d807b8a5b3fa90fbdc", size = 853922, upload-time = "2026-03-29T15:01:55.233Z" } +sdist = { url = "https://files.pythonhosted.org/packages/9e/26/d1015444da4d952a1ca487a236b522eb979766f0295a0bd0c5fc089989a9/pymdown_extensions-10.21.3.tar.gz", hash = "sha256:72cfcf55f07aea0d4af2c4f11dd4e52466ddfb1bb819673146398e0bd3a77354", size = 854140, upload-time = "2026-05-13T12:57:32.267Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/f7/27/a2fc51a4a122dfd1015e921ae9d22fee3d20b0b8080d9a704578bf9deece/pymdown_extensions-10.21.2-py3-none-any.whl", hash = "sha256:5c0fd2a2bea14eb39af8ff284f1066d898ab2187d81b889b75d46d4348c01638", size = 268901, upload-time = "2026-03-29T15:01:53.244Z" }, + { url = "https://files.pythonhosted.org/packages/7e/85/545a951eecc270fcd688288c600017e2050a1aacb56c711d208586d3e470/pymdown_extensions-10.21.3-py3-none-any.whl", hash = "sha256:d7a5d08014fc571e80ca21dd6f854e31f94c489800350564d55d15b3c41e76b6", size = 269002, upload-time = "2026-05-13T12:57:30.296Z" }, ] [[package]] @@ -952,7 +952,7 @@ requires-dist = [ { name = "jinja2", specifier = ">=3.1" }, { name = "markdown", specifier = ">=3.7" }, { name = "pygments", specifier = ">=2.20" }, - { name = "pymdown-extensions", specifier = ">=10.21.2" }, + { name = "pymdown-extensions", specifier = ">=10.21.3" }, { name = "pyyaml", specifier = ">=6.0.2" }, { name = "tomli", specifier = ">=2.4.0" }, ]