diff --git a/crates/zensical/src/python/collector/reference/link.rs b/crates/zensical/src/python/collector/reference/link.rs
index 96ea13c..168c354 100644
--- a/crates/zensical/src/python/collector/reference/link.rs
+++ b/crates/zensical/src/python/collector/reference/link.rs
@@ -46,6 +46,8 @@ pub enum LinkKind {
     Autolink,
     /// Wikilink.
     Wikilink,
+    /// HTML.
+    Html,
 }
 
 /// Link reference kind.
@@ -119,6 +121,7 @@ impl<'a, 'py> FromPyObject<'a, 'py> for LinkKind {
             "image" => Ok(Self::Image),
             "autolink" => Ok(Self::Autolink),
             "wikilink" => Ok(Self::Wikilink),
+            "html" => Ok(Self::Html),
             _ => Err(PyValueError::new_err("Invalid kind")),
         }
     }
diff --git a/python/tests/unit/collectors/__init__.py b/python/tests/unit/collectors/__init__.py
new file mode 100644
index 0000000..576d3ea
--- /dev/null
+++ b/python/tests/unit/collectors/__init__.py
@@ -0,0 +1,22 @@
+# Copyright (c) 2025-2026 Zensical and contributors
+
+# SPDX-License-Identifier: MIT
+# All contributions are certified under the DCO
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
diff --git a/python/tests/unit/collectors/test_references.py b/python/tests/unit/collectors/test_references.py
new file mode 100644
index 0000000..d256677
--- /dev/null
+++ b/python/tests/unit/collectors/test_references.py
@@ -0,0 +1,2068 @@
+# Copyright (c) 2025-2026 Zensical and contributors
+
+# SPDX-License-Identifier: MIT
+# All contributions are certified under the DCO
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from zensical.collectors import references
+from zensical.collectors.references import (
+    FootnoteDefinition,
+    FootnoteReference,
+    Link,
+    LinkDefinition,
+    LinkReference,
+    Reference,
+)
+
+if TYPE_CHECKING:
+    from zensical.utilities.span import Span
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestLinks:
+    """Tests for links."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text", "expected_href"),
+        [
+            pytest.param(
+                b"[text](href)",
+                b"text",
+                b"href",
+                id="link",
+            ),
+            pytest.param(
+                b'[text](href "Title")',
+                b"text",
+                b"href",
+                id="link-with-title",
+            ),
+            pytest.param(
+                b'[text](href more"Title")',
+                b"text",
+                b"href more",
+                id="link-with-title, whitespace",
+            ),
+            pytest.param(
+                b'[text](href more "Title")',
+                b"text",
+                b"href more",
+                id="link-with-title, whitespace, trailing",
+            ),
+            pytest.param(
+                b"[](href)",
+                b"",
+                b"href",
+                id="link-with-empty-text",
+            ),
+            pytest.param(
+                b"[text]()",
+                b"text",
+                b"",
+                id="link-with-empty-href",
+            ),
+            pytest.param(
+                b"[]()",
+                b"",
+                b"",
+                id="link-with-empty-text-and-href",
+            ),
+            pytest.param(
+                b"[text \\]](href)",
+                b"text \\]",
+                b"href",
+                id="link-with-escaped-brackets-in-text",
+            ),
+            pytest.param(
+                b"[text]((href))",
+                b"text",
+                b"(href)",
+                id="link-with-parens-in-href",
+            ),
+            pytest.param(
+                b"[text](href 'Title')",
+                b"text",
+                b"href",
+                id="link-with-title, single quotes",
+            ),
+            pytest.param(
+                b"[text](href more'Title')",
+                b"text",
+                b"href more",
+                id="link-with-title, single quotes, whitespace",
+            ),
+            pytest.param(
+                b"[text](href more 'Title')",
+                b"text",
+                b"href more",
+                id="link-with-title, single quotes, whitespace, trailing",
+            ),
+        ],
+    )
+    def test_link(
+        self, md: bytes, expected_text: bytes, expected_href: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == expected_text
+        assert text(md, links[0].href) == expected_href
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text", "expected_href"),
+        [
+            pytest.param(
+                b"[text](href){}",
+                b"text",
+                b"href",
+                id="link-with-attr",
+            ),
+            pytest.param(
+                b"[text](href){ .class }",
+                b"text",
+                b"href",
+                id="link-with-class-attr",
+            ),
+            pytest.param(
+                b"[text](href){ #id }",
+                b"text",
+                b"href",
+                id="link-with-id-attr",
+            ),
+            pytest.param(
+                b'[text](href){ target="_blank" }',
+                b"text",
+                b"href",
+                id="link-with-target-attr",
+            ),
+            pytest.param(
+                b'[text](href){ .class #id target="_blank" }',
+                b"text",
+                b"href",
+                id="link-with-multiple-attrs",
+            ),
+            pytest.param(
+                b'[text](href) { target="_blank" }',
+                b"text",
+                b"href",
+                id="link-with-spaced-attr, invalid",
+            ),
+        ],
+    )
+    def test_link_with_attr_list(
+        self, md: bytes, expected_text: bytes, expected_href: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == expected_text
+        assert text(md, links[0].href) == expected_href
+
+    @pytest.mark.parametrize(
+        ("md", "expected_href"),
+        [
+            pytest.param(
+                b"[text](<href>)",
+                b"href",
+                id="link-with-angle-brackets",
+            ),
+            pytest.param(
+                b'[text](<href> "title")',
+                b"href",
+                id="link-with-angle-brackets-and-title",
+            ),
+            pytest.param(
+                b'[text](<href> more"Title")',
+                b"<href> more",
+                id="link-with-angle-brackets-and-title, whitespace",
+            ),
+            pytest.param(
+                b'[text](<href> more "Title")',
+                b"<href> more",
+                id="link-with-angle-brackets-and-title, whitespace, trailing",
+            ),
+            pytest.param(
+                b"[text](<>)",
+                b"",
+                id="link-with-empty-angle-brackets",
+            ),
+            pytest.param(
+                b"[text](<href)",
+                b"<href",
+                id="link-with-missing-closing-bracket",
+            ),
+        ],
+    )
+    def test_link_with_angle_brackets(
+        self, md: bytes, expected_href: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].href) == expected_href
+
+    def test_link_text_with_newline(self) -> None:
+        md = b"[text\nmore text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == b"text\nmore text"
+        assert text(md, links[0].href) == b"href"
+
+    def test_link_href_with_newline(self) -> None:
+        md = b"[text](hr\nef)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"hr\nef"
+
+    # --- negative cases ---
+
+    def test_no_link_escaped_brackets(self) -> None:
+        md = b"\\[text\\](href)"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_link_escaped_opening_bracket(self) -> None:
+        md = b"\\[text](href)"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_link_escaped_closing_bracket(self) -> None:
+        md = b"[text\\](href)"
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestLinkReferences:
+    """Tests for link references."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text", "expected_id"),
+        [
+            pytest.param(
+                b"[text][id]",
+                b"text",
+                b"id",
+                id="link-ref",
+            ),
+            pytest.param(
+                b"[text][]",
+                b"text",
+                b"text",
+                id="link-ref, collapsed",
+            ),
+            pytest.param(
+                b"[text]",
+                b"text",
+                b"text",
+                id="link-ref, shortcut",
+            ),
+            pytest.param(
+                b"[][id]",
+                b"",
+                b"id",
+                id="link-ref-with-empty-text",
+            ),
+            pytest.param(
+                b"[][]",
+                b"",
+                b"",
+                id="link-ref-with-empty-text-and-id",
+            ),
+            pytest.param(
+                b"[text \\]][id]",
+                b"text \\]",
+                b"id",
+                id="link-ref-with-escaped-brackets-in-text",
+            ),
+        ],
+    )
+    def test_link_ref(
+        self, md: bytes, expected_text: bytes, expected_id: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == expected_text
+        assert text(md, link_refs[0].id) == expected_id
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text", "expected_id"),
+        [
+            pytest.param(
+                b"[text][id]{}",
+                b"text",
+                b"id",
+                id="link-ref-with-attr",
+            ),
+            pytest.param(
+                b"[text][]{}",
+                b"text",
+                b"text",
+                id="link-ref-with-attr, collapsed",
+            ),
+            pytest.param(
+                b"[text]{}",
+                b"text",
+                b"text",
+                id="link-ref-with-attr, shortcut",
+            ),
+            pytest.param(
+                b"[text][id]{ .class }",
+                b"text",
+                b"id",
+                id="link-ref-with-class-attr",
+            ),
+            pytest.param(
+                b"[text][id]{ #id }",
+                b"text",
+                b"id",
+                id="link-ref-with-id-attr",
+            ),
+            pytest.param(
+                b'[text][id]{ target="_blank" }',
+                b"text",
+                b"id",
+                id="link-ref-with-target-attr",
+            ),
+            pytest.param(
+                b'[text][id]{ .class #id target="_blank" }',
+                b"text",
+                b"id",
+                id="link-ref-with-multiple-attrs",
+            ),
+            pytest.param(
+                b'[text][id] { target="_blank" }',
+                b"text",
+                b"id",
+                id="link-ref-with-spaced-attr, invalid",
+            ),
+        ],
+    )
+    def test_link_ref_with_attr_list(
+        self, md: bytes, expected_text: bytes, expected_id: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == expected_text
+        assert text(md, link_refs[0].id) == expected_id
+
+    def test_link_ref_with_space(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 link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"id"
+        assert text(md, link_refs[0].id) == b"id"
+
+    def test_link_ref_with_footnote(self) -> None:
+        md = b"[id][^note]"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"id"
+        assert text(md, link_refs[0].id) == b"id"
+
+        note_refs = footnote_refs_only(refs)
+        assert len(note_refs) == 1
+        assert text(md, note_refs[0].id) == b"note"
+
+    def test_link_ref_text_with_newline(self) -> None:
+        md = b"[text\nmore text][id]"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"text\nmore text"
+        assert text(md, link_refs[0].id) == b"id"
+
+    def test_link_ref_text_brackets_in_id(self) -> None:
+        md = b"[text][[id]]"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"text"
+        assert text(md, link_refs[0].id) == b"text"
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "wikilink"
+        assert text(md, links[0].text) == b"id"
+        assert text(md, links[0].href) == b"id"
+
+    # --- negative cases ---
+
+    def test_no_link_ref_escaped_brackets(self) -> None:
+        md = b"\\[text\\]"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_link_ref_escaped_opening_bracket(self) -> None:
+        md = b"\\[text]"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_link_ref_escaped_closing_bracket(self) -> None:
+        md = b"[text\\]"
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestLinkDefinitions:
+    """Tests for link definitions."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_id", "expected_href"),
+        [
+            pytest.param(
+                b"[id]: href",
+                b"id",
+                b"href",
+                id="link-def",
+            ),
+            pytest.param(
+                b"[multi word id]: href",
+                b"multi word id",
+                b"href",
+                id="link-def, multi-word",
+            ),
+            pytest.param(
+                b'[id]: href "Title"',
+                b"id",
+                b"href",
+                id="link-def-with-title",
+            ),
+            pytest.param(
+                b"[id]: href 'Title'",
+                b"id",
+                b"href",
+                id="link-def-with-title, single quotes",
+            ),
+            pytest.param(
+                b"   [id]: href\n",
+                b"id",
+                b"href",
+                id="link-def-with-indent",
+            ),
+        ],
+    )
+    def test_link_def(
+        self, md: bytes, expected_id: bytes, expected_href: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_defs = link_defs_only(refs)
+        assert len(link_defs) == 1
+        assert text(md, link_defs[0].id) == expected_id
+        assert text(md, link_defs[0].href) == expected_href
+
+    @pytest.mark.parametrize(
+        ("md", "expected_id", "expected_href"),
+        [
+            pytest.param(
+                b"[id]: <href>\nid",
+                b"id",
+                b"href",
+                id="link-def",
+            ),
+            pytest.param(
+                b"[multi word id]: <href>",
+                b"multi word id",
+                b"href",
+                id="link-def, multi-word",
+            ),
+            pytest.param(
+                b'[id]: <href> "Title"',
+                b"id",
+                b"href",
+                id="link-def-with-title",
+            ),
+            pytest.param(
+                b"   [id]: <href>\n",
+                b"id",
+                b"href",
+                id="link-def-with-indent",
+            ),
+        ],
+    )
+    def test_link_def_with_angle_brackets(
+        self, md: bytes, expected_id: bytes, expected_href: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_defs = link_defs_only(refs)
+        assert len(link_defs) == 1
+        assert text(md, link_defs[0].id) == expected_id
+        assert text(md, link_defs[0].href) == expected_href
+
+    def test_link_def_title_on_next_line(self) -> None:
+        md = b'[id]: href\n  "Title"'
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_defs = link_defs_only(refs)
+        assert len(link_defs) == 1
+        assert text(md, link_defs[0].id) == b"id"
+        assert text(md, link_defs[0].href) == b"href"
+
+    # --- negative cases ---
+
+    def test_no_link_def_empty_href(self) -> None:
+        md = b"[id]:"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+
+    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
+
+    def test_no_link_def_prefix(self) -> None:
+        md = b"text [id]: href"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestImages:
+    """Tests for images."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_alt", "expected_href"),
+        [
+            pytest.param(
+                b"![alt](image.png)",
+                b"alt",
+                b"image.png",
+                id="image",
+            ),
+            pytest.param(
+                b'![alt](image.png "Title")',
+                b"alt",
+                b"image.png",
+                id="image-with-title",
+            ),
+            pytest.param(
+                b"![](image.png)",
+                b"",
+                b"image.png",
+                id="image-with-empty-alt",
+            ),
+            pytest.param(
+                b"![alt]()",
+                b"alt",
+                b"",
+                id="image-with-empty-href",
+            ),
+            pytest.param(
+                b"![]()",
+                b"",
+                b"",
+                id="image-with-empty-alt-and-href",
+            ),
+            pytest.param(
+                b"![alt [[]]](image.png)",
+                b"alt [[]]",
+                b"image.png",
+                id="image-with-brackets-in-alt",
+            ),
+            pytest.param(
+                b"![alt \\]](image.png)",
+                b"alt \\]",
+                b"image.png",
+                id="image-with-escaped-brackets-in-alt",
+            ),
+            pytest.param(
+                b"![alt]((href))",
+                b"alt",
+                b"(href)",
+                id="image-with-parens-in-href",
+            ),
+        ],
+    )
+    def test_image(
+        self, md: bytes, expected_alt: bytes, expected_href: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "image"
+        assert text(md, links[0].text) == expected_alt
+        assert text(md, links[0].href) == expected_href
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text", "expected_href"),
+        [
+            pytest.param(
+                b"![alt](image.png){}",
+                b"alt",
+                b"image.png",
+                id="image-with-attr",
+            ),
+            pytest.param(
+                b"![alt](image.png){ .class }",
+                b"alt",
+                b"image.png",
+                id="image-with-class-attr",
+            ),
+            pytest.param(
+                b"![alt](image.png){ #id }",
+                b"alt",
+                b"image.png",
+                id="image-with-id-attr",
+            ),
+            pytest.param(
+                b'![alt](image.png){ loading="lazy" }',
+                b"alt",
+                b"image.png",
+                id="image-with-loading-attr",
+            ),
+            pytest.param(
+                b'![alt](image.png){ .class #id loading="lazy" }',
+                b"alt",
+                b"image.png",
+                id="image-with-multiple-attrs",
+            ),
+            pytest.param(
+                b'![alt](image.png) { loading="lazy" }',
+                b"alt",
+                b"image.png",
+                id="image-with-spaced-attr, invalid",
+            ),
+        ],
+    )
+    def test_image_with_attr_list(
+        self, md: bytes, expected_text: bytes, expected_href: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "image"
+        assert text(md, links[0].text) == expected_text
+        assert text(md, links[0].href) == expected_href
+
+    def test_image_with_angle_brackets(self) -> None:
+        md = b"![alt](<image.png>)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "image"
+        assert text(md, links[0].text) == b"alt"
+        assert text(md, links[0].href) == b"image.png"
+
+    def test_image_ref_with_space(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 link_refs[0].kind == "image"
+        assert text(md, link_refs[0].text) == b"id"
+        assert text(md, link_refs[0].id) == b"id"
+
+    def test_image_text_with_newline(self) -> None:
+        md = b"![alt\nmore text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "image"
+        assert text(md, links[0].text) == b"alt\nmore text"
+        assert text(md, links[0].href) == b"href"
+
+    # --- negative cases ---
+
+    def test_no_image_escaped_bang(self) -> None:
+        md = b"\\![alt](image.png)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == b"alt"
+        assert text(md, links[0].href) == b"image.png"
+
+    def test_no_image_spaced_bang(self) -> None:
+        md = b"! [alt](image.png)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == b"alt"
+        assert text(md, links[0].href) == b"image.png"
+
+    def test_no_image_only_bang(self) -> None:
+        md = b"!image.png"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_image_escaped_brackets(self) -> None:
+        md = b"!\\[alt\\](image.png)"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_image_escaped_opening_bracket(self) -> None:
+        md = b"!\\[alt](image.png)"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_image_escaped_closing_bracket(self) -> None:
+        md = b"![alt\\](image.png)"
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestImageReferences:
+    """Tests for image references."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_alt", "expected_id"),
+        [
+            pytest.param(
+                b"![alt][id]",
+                b"alt",
+                b"id",
+                id="image-ref",
+            ),
+            pytest.param(
+                b"![alt][]",
+                b"alt",
+                b"alt",
+                id="image-ref, collapsed",
+            ),
+            pytest.param(
+                b"![id]",
+                b"id",
+                b"id",
+                id="image-ref, shortcut",
+            ),
+            pytest.param(
+                b"![][id]",
+                b"",
+                b"id",
+                id="image-ref-with-empty-alt",
+            ),
+            pytest.param(
+                b"![][]",
+                b"",
+                b"",
+                id="image-ref-with-empty-alt-and-id",
+            ),
+            pytest.param(
+                b"![alt [[]]][id]",
+                b"alt [[]]",
+                b"id",
+                id="image-ref-with-brackets-in-text",
+            ),
+            pytest.param(
+                b"![alt \\]][id]",
+                b"alt \\]",
+                b"id",
+                id="image-ref-with-escaped-brackets-in-text",
+            ),
+        ],
+    )
+    def test_image_ref(
+        self, md: bytes, expected_alt: bytes, expected_id: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "image"
+        assert text(md, link_refs[0].text) == expected_alt
+        assert text(md, link_refs[0].id) == expected_id
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text", "expected_id"),
+        [
+            pytest.param(
+                b"![alt][image-id]{}",
+                b"alt",
+                b"image-id",
+                id="image-ref-with-attr",
+            ),
+            pytest.param(
+                b"![alt][]{}",
+                b"alt",
+                b"alt",
+                id="image-ref-with-attr, collapsed",
+            ),
+            pytest.param(
+                b"![alt]{}",
+                b"alt",
+                b"alt",
+                id="image-ref-with-attr, shortcut",
+            ),
+            pytest.param(
+                b"![alt][id]{ .class }",
+                b"alt",
+                b"id",
+                id="image-ref-with-class-attr",
+            ),
+            pytest.param(
+                b"![alt][id]{ #id }",
+                b"alt",
+                b"id",
+                id="image-ref-with-id-attr",
+            ),
+            pytest.param(
+                b'![alt][id]{ loading="lazy" }',
+                b"alt",
+                b"id",
+                id="image-ref-with-loading-attr",
+            ),
+            pytest.param(
+                b'![alt][id]{ .class #id loading="lazy" }',
+                b"alt",
+                b"id",
+                id="image-ref-with-multiple-attrs",
+            ),
+            pytest.param(
+                b'![alt][id] { loading="lazy" }',
+                b"alt",
+                b"id",
+                id="image-ref-with-spaced-attr, invalid",
+            ),
+        ],
+    )
+    def test_image_ref_with_attr_list(
+        self, md: bytes, expected_text: bytes, expected_id: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "image"
+        assert text(md, link_refs[0].text) == expected_text
+        assert text(md, link_refs[0].id) == expected_id
+
+    def test_image_ref_text_with_newline(self) -> None:
+        md = b"![alt\nmore text][id]"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "image"
+        assert text(md, link_refs[0].text) == b"alt\nmore text"
+        assert text(md, link_refs[0].id) == b"id"
+
+    # --- negative cases ---
+
+    def test_no_image_ref_escaped_bang(self) -> None:
+        md = b"\\![alt][id]"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"alt"
+        assert text(md, link_refs[0].id) == b"id"
+
+    def test_no_image_ref_escaped_brackets(self) -> None:
+        md = b"!\\[text\\]"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_image_ref_escaped_opening_bracket(self) -> None:
+        md = b"!\\[text]"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_no_image_ref_escaped_closing_bracket(self) -> None:
+        md = b"![text\\]"
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestInnerLinks:
+    """Tests for links in links and images."""
+
+    def test_link_ref_in_link(self) -> None:
+        md = b"[text[more]](href)"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == b"text[more]"
+        assert text(md, links[0].href) == b"href"
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"more"
+        assert text(md, link_refs[0].id) == b"more"
+
+    def test_link_ref_in_link_ref(self) -> None:
+        md = b"[text[more]][id]"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 2
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"text[more]"
+        assert text(md, link_refs[0].id) == b"id"
+        assert link_refs[1].kind == "link"
+        assert text(md, link_refs[1].text) == b"more"
+        assert text(md, link_refs[1].id) == b"more"
+
+    def test_image_in_link(self) -> None:
+        md = b"[![alt](image.png)](href)"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        links = links_only(refs)
+        assert len(links) == 2
+        assert links[0].kind == "link"
+        assert text(md, links[0].href) == b"href"
+        assert links[1].kind == "image"
+        assert text(md, links[1].text) == b"alt"
+        assert text(md, links[1].href) == b"image.png"
+
+    def test_image_ref_in_link(self) -> None:
+        md = b"[![alt][image-id]](href)"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].href) == b"href"
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "image"
+        assert text(md, link_refs[0].text) == b"alt"
+        assert text(md, link_refs[0].id) == b"image-id"
+
+    def test_image_in_link_ref(self) -> None:
+        md = b"[![alt](image.png)][id]"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "image"
+        assert text(md, links[0].text) == b"alt"
+        assert text(md, links[0].href) == b"image.png"
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].id) == b"id"
+
+    def test_image_ref_in_link_ref(self) -> None:
+        md = b"[![alt][image-id]][id]"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 2
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].id) == b"id"
+        assert link_refs[1].kind == "image"
+        assert text(md, link_refs[1].text) == b"alt"
+        assert text(md, link_refs[1].id) == b"image-id"
+
+    def test_no_link_ref_in_link(self) -> None:
+        md = b"[text\\[more\\]](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == b"text\\[more\\]"
+        assert text(md, links[0].href) == b"href"
+
+    def test_no_link_ref_in_link_ref(self) -> None:
+        md = b"[text\\[more\\]][id]"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"text\\[more\\]"
+        assert text(md, link_refs[0].id) == b"id"
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestAutolinks:
+    """Tests for autolinks."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_href"),
+        [
+            pytest.param(
+                b"<https://example.com>",
+                b"https://example.com",
+                id="autolink-https",
+            ),
+            pytest.param(
+                b"<http://example.com>",
+                b"http://example.com",
+                id="autolink-http",
+            ),
+        ],
+    )
+    def test_autolink(self, md: bytes, expected_href: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "autolink"
+        assert text(md, links[0].text) == expected_href
+        assert text(md, links[0].href) == expected_href
+
+    # --- negative cases ---
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"<not-a-url>",
+                id="autolink-scheme, missing",
+            ),
+            pytest.param(
+                b"<ftp://example.com>",
+                id="autolink-scheme, unsupported",
+            ),
+            pytest.param(
+                b"<>",
+                id="autolink-empty",
+            ),
+        ],
+    )
+    def test_no_autolink(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestWikilinks:
+    """Tests for wikilinks."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text"),
+        [
+            pytest.param(
+                b"[[Page]]",
+                b"Page",
+                id="wikilink",
+            ),
+            pytest.param(
+                b"[[Page|display]]",
+                b"Page|display",
+                id="wikilink-with-text",
+            ),
+        ],
+    )
+    def test_wikilink(self, md: bytes, expected_text: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "wikilink"
+        assert text(md, links[0].text) == expected_text
+        assert text(md, links[0].href) == expected_text
+
+    # --- negative cases ---
+
+    @pytest.mark.parametrize(
+        ("md", "expected_text", "expected_id"),
+        [
+            pytest.param(
+                b"[[Page]][id]",
+                b"[Page]",
+                b"id",
+                id="link-ref",
+            ),
+            pytest.param(
+                b"[[Page]][]",
+                b"[Page]",
+                b"[Page]",
+                id="link-ref, collapsed",
+            ),
+            pytest.param(
+                b"[[Page]]\n[id]",
+                b"[Page]",
+                b"id",
+                id="link-ref-with-newline",
+            ),
+        ],
+    )
+    def test_no_wikilink(
+        self, md: bytes, expected_text: bytes, expected_id: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 2
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 2
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == expected_text
+        assert text(md, link_refs[0].id) == expected_id
+        assert link_refs[1].kind == "link"
+        assert text(md, link_refs[1].text) == b"Page"
+        assert text(md, link_refs[1].id) == b"Page"
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestFootnoteReferences:
+    """Tests for footnote references."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_id"),
+        [
+            pytest.param(
+                b"[^1]",
+                b"1",
+                id="footnote-ref",
+            ),
+            pytest.param(
+                b"[^note]",
+                b"note",
+                id="footnote-ref-with-name",
+            ),
+            pytest.param(
+                b"[^@#$%]",
+                b"@#$%",
+                id="footnote-ref-with-special-chars",
+            ),
+        ],
+    )
+    def test_footnote_ref(self, md: bytes, expected_id: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        note_refs = footnote_refs_only(refs)
+        assert len(note_refs) == 1
+        assert text(md, note_refs[0].id) == expected_id
+
+    # --- negative cases ---
+
+    @pytest.mark.parametrize(
+        ("md", "expected_id"),
+        [
+            pytest.param(
+                b"[^]",
+                b"^",
+                id="link-ref",
+            ),
+            pytest.param(
+                b"[^ ]",
+                b"^ ",
+                id="link-ref, space",
+            ),
+            pytest.param(
+                b"[^multi word note]",
+                b"^multi word note",
+                id="link-ref, separated",
+            ),
+        ],
+    )
+    def test_no_footnote_ref(self, md: bytes, expected_id: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == expected_id
+        assert text(md, link_refs[0].id) == expected_id
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestFootnoteDefinitions:
+    """Tests for footnote definitions."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_id", "expected_body"),
+        [
+            pytest.param(
+                b"[^1]: body",
+                b"1",
+                b"body",
+                id="footnote-def",
+            ),
+            pytest.param(
+                b"[^note]: body",
+                b"note",
+                b"body",
+                id="footnote-def-with-name",
+            ),
+            pytest.param(
+                b"[^@#$%]: body",
+                b"@#$%",
+                b"body",
+                id="footnote-def-with-special-chars",
+            ),
+            pytest.param(
+                b"[^1]: body\n    continuation\n    and so on.",
+                b"1",
+                b"body\n    continuation\n    and so on.",
+                id="footnote-def, multiple lines",
+            ),
+        ],
+    )
+    def test_footnote_def(
+        self, md: bytes, expected_id: bytes, expected_body: bytes
+    ) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        note_defs = footnote_defs_only(refs)
+        assert len(note_defs) == 1
+        assert text(md, note_defs[0].id) == expected_id
+        assert text(md, note_defs[0].body) == expected_body
+
+    def test_footnote_def_with_link(self) -> None:
+        md = b"[^1]: [text](href)"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        note_defs = footnote_defs_only(refs)
+        assert len(note_defs) == 1
+        assert text(md, note_defs[0].id) == b"1"
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "link"
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"href"
+
+    def test_footnote_def_with_link_ref(self) -> None:
+        md = b"[^1]: [id]"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        note_defs = footnote_defs_only(refs)
+        assert len(note_defs) == 1
+        assert text(md, note_defs[0].id) == b"1"
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "link"
+        assert text(md, link_refs[0].text) == b"id"
+        assert text(md, link_refs[0].id) == b"id"
+
+    def test_footnote_def_with_link_def(self) -> None:
+        md = b"[^1]: body\n[id]: href"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        note_defs = footnote_defs_only(refs)
+        assert len(note_defs) == 1
+        assert text(md, note_defs[0].id) == b"1"
+
+        link_defs = link_defs_only(refs)
+        assert len(link_defs) == 1
+        assert text(md, link_defs[0].id) == b"id"
+        assert text(md, link_defs[0].href) == b"href"
+
+    def test_footnote_def_with_image(self) -> None:
+        md = b"[^1]: ![alt](href)"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        note_defs = footnote_defs_only(refs)
+        assert len(note_defs) == 1
+        assert text(md, note_defs[0].id) == b"1"
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "image"
+        assert text(md, links[0].text) == b"alt"
+        assert text(md, links[0].href) == b"href"
+
+    def test_footnote_def_with_image_ref(self) -> None:
+        md = b"[^1]: ![id]"
+        refs = collect(md)
+        assert len(refs) == 2
+
+        note_defs = footnote_defs_only(refs)
+        assert len(note_defs) == 1
+        assert text(md, note_defs[0].id) == b"1"
+
+        link_refs = link_refs_only(refs)
+        assert len(link_refs) == 1
+        assert link_refs[0].kind == "image"
+        assert text(md, link_refs[0].text) == b"id"
+        assert text(md, link_refs[0].id) == b"id"
+
+    def test_no_footnote_def_with_inline_code(self) -> None:
+        md = b"[^1]: `[code]`"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        note_defs = footnote_defs_only(refs)
+        assert len(note_defs) == 1
+
+    # --- negative cases ---
+
+    def test_no_footnote_def_prefix(self) -> None:
+        md = b"text [^1]: body\n"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        note_refs = footnote_refs_only(refs)
+        assert len(note_refs) == 1
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestFencedCodeBlocks:
+    """Tests for fenced code blocks."""
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"```\n[text](href)\n```",
+                id="fenced-code-3-backticks",
+            ),
+            pytest.param(
+                b"``` python\n[text](href)\n```",
+                id="fenced-code-3-backticks-lang",
+            ),
+            pytest.param(
+                b"````\n[text](href)\n````",
+                id="fenced-code-4-backticks",
+            ),
+            pytest.param(
+                b"```` py\n[text](href)\n````",
+                id="fenced-code-4-backticks-lang",
+            ),
+            pytest.param(
+                b"~~~\n[text](href)\n~~~",
+                id="fenced-code-3-tildes",
+            ),
+            pytest.param(
+                b"~~~ python\n[text](href)\n~~~",
+                id="fenced-code-3-tildes-lang",
+            ),
+            pytest.param(
+                b"~~~~\n[text](href)\n~~~~",
+                id="fenced-code-4-tildes",
+            ),
+            pytest.param(
+                b"~~~~ py\n[text](href)\n~~~~",
+                id="fenced-code-4-tildes-lang",
+            ),
+        ],
+    )
+    def test_fenced_code(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_fenced_code_with_link_after(self) -> None:
+        md = b"```\n[text](href)\n```\n[after](href)"
+        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"
+
+    def test_fenced_code_with_link_before(self) -> None:
+        md = b"[before](href)\n```\n[text](href)\n```"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"before"
+        assert text(md, links[0].href) == b"href"
+
+    # --- negative cases ---
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"```\n[text](href)\n````",
+                id="fenced-code-unbalanced-backticks",
+            ),
+            pytest.param(
+                b"```\n[text](href)",
+                id="fenced-code-missing-backticks",
+            ),
+            pytest.param(
+                b"```\n[text](href)\n~~~",
+                id="fenced-code-backticks-tildes",
+            ),
+            pytest.param(
+                b"~~~\n[text](href)\n```",
+                id="fenced-code-tildes-backticks",
+            ),
+        ],
+    )
+    def test_no_fenced_code(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"href"
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestInlineCode:
+    """Tests for inline code."""
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"`[text](href)`",
+                id="inline-code",
+            ),
+            pytest.param(
+                b"``[text](href)``",
+                id="inline-code-2-backticks",
+            ),
+            pytest.param(
+                b"`` [text](href) ``",
+                id="inline-code-2-backticks, spaces",
+            ),
+            pytest.param(
+                b"```[text](href)```",
+                id="inline-code-3-backticks",
+            ),
+            pytest.param(
+                b"``text`[text](href)``",
+                id="inline-code, inner backticks",
+            ),
+        ],
+    )
+    def test_inline_code(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_inline_code_with_link_after(self) -> None:
+        md = b"`code` [text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"href"
+
+    def test_inline_code_with_link_before(self) -> None:
+        md = b"[text](href) `code`"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"href"
+
+    # --- negative cases ---
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"`[text](href)\n``",
+                id="inline-code-unbalanced-backticks",
+            ),
+            pytest.param(
+                b"`\n[text](href)",
+                id="inline-code-missing-backticks",
+            ),
+        ],
+    )
+    def test_no_inline_code(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"href"
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestMath:
+    """Tests for math blocks and inline math."""
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"$$\n[text](href)\n$$",
+                id="math-block",
+            ),
+            pytest.param(
+                b"$$ [text](href) $$",
+                id="math-block, single line",
+            ),
+            pytest.param(
+                b"$[text](href)$",
+                id="math-inline",
+            ),
+            pytest.param(
+                b"\\[\n[text](href)\n\\]",
+                id="match-block-brackets",
+            ),
+            pytest.param(
+                b"\\[ [text](href) \\]",
+                id="match-block-brackets, single line",
+            ),
+            pytest.param(
+                b"\\([text](href)\\)",
+                id="math-inline-parens",
+            ),
+        ],
+    )
+    def test_math(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+    def test_math_with_link_after(self) -> None:
+        md = b"$$\n[text](href)\n$$\n[after](href)"
+        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"
+
+    def test_math_with_link_before(self) -> None:
+        md = b"[before](href)\n$$\n[text](href)\n$$"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"before"
+        assert text(md, links[0].href) == b"href"
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestHtmlLinks:
+    """Tests for HTML elements with links."""
+
+    @pytest.mark.parametrize(
+        ("md", "expected_href"),
+        [
+            pytest.param(
+                b'<a href="href">text</a>',
+                b"href",
+                id="html-a-href",
+            ),
+            pytest.param(
+                b'<div>\n<a href="href">text</a>\n</div>',
+                b"href",
+                id="html-a-href, in block",
+            ),
+            pytest.param(
+                b'<img src="image.png">',
+                b"image.png",
+                id="html-img-src",
+            ),
+            pytest.param(
+                b'<img src="image.png" />',
+                b"image.png",
+                id="html-img-src, self-closing",
+            ),
+            pytest.param(
+                b'<div>\n<img src="image.png">\n</div>',
+                b"image.png",
+                id="html-img-src, in block",
+            ),
+            pytest.param(
+                b'<p>\n<img\nsrc="image.png"\n>\n</p>',
+                b"image.png",
+                id="html-p-img-src, in block, multiple lines",
+            ),
+            pytest.param(
+                b'<link href="style.css">',
+                b"style.css",
+                id="html-link-href",
+            ),
+            pytest.param(
+                b'<script src="script.js"></script>',
+                b"script.js",
+                id="html-script-src",
+            ),
+            pytest.param(
+                b'<audio src="audio.mp3">',
+                b"audio.mp3",
+                id="html-audio-src",
+            ),
+            pytest.param(
+                b'<video src="video.mp4">',
+                b"video.mp4",
+                id="html-video-src",
+            ),
+            pytest.param(
+                b'<p>\n<img src="image.png">\n</p>',
+                b"image.png",
+                id="html-p-img-src, in block",
+            ),
+        ],
+    )
+    def test_html_link(self, md: bytes, expected_href: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].kind == "html"
+        assert text(md, links[0].text) == expected_href
+        assert text(md, links[0].href) == expected_href
+
+    # --- negative cases ---
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b'<!-- <img src="image.png"> -->',
+                id="html-link, in comment",
+            ),
+            pytest.param(
+                b'<div>\n<!-- <img src="image.png"> -->\n</div>',
+                id="html-link, in comment in block",
+            ),
+        ],
+    )
+    def test_no_html_link(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestHtmlComments:
+    """Tests for HTML comments."""
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"<!-- [text](href) -->",
+                id="html-comment",
+            ),
+            pytest.param(
+                b"<!--\n[text](href)\n-->",
+                id="html-comment-multi-line",
+            ),
+        ],
+    )
+    def test_html_comment(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestHtmlBlocks:
+    """Tests for HTML blocks."""
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"<div>\n[text](href)\n</div>",
+                id="html-block, div",
+            ),
+            pytest.param(
+                b"<p>\n[text](href)\n</p>",
+                id="html-block, p",
+            ),
+            pytest.param(
+                b"<blockquote>\n[text](href)\n</blockquote>",
+                id="html-block, blockquote",
+            ),
+            pytest.param(
+                b"<ul>\n[text](href)\n</ul>",
+                id="html-block, ul",
+            ),
+        ],
+    )
+    def test_html_block(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"<div markdown>\n[text](href)\n</div>",
+                id="html-block, div",
+            ),
+            pytest.param(
+                b"<p markdown>\n[text](href)\n</p>",
+                id="html-block, p",
+            ),
+            pytest.param(
+                b"<blockquote markdown>\n[text](href)\n</blockquote>",
+                id="html-block, blockquote",
+            ),
+            pytest.param(
+                b"<ul markdown>\n[text](href)\n</ul>",
+                id="html-block, ul",
+            ),
+        ],
+    )
+    def test_html_block_with_markdown_attr(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"href"
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"<a>\n[text](href)\n</a>",
+                id="html-inline, a",
+            ),
+            pytest.param(
+                b"<small>[text](href)</small>",
+                id="html-inline, small",
+            ),
+            pytest.param(
+                b"<span>[text](href)</span>",
+                id="html-inline, span",
+            ),
+            pytest.param(
+                b"<em>[text](href)</em>",
+                id="html-inline, em",
+            ),
+        ],
+    )
+    def test_html_inline(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert text(md, links[0].text) == b"text"
+        assert text(md, links[0].href) == b"href"
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestJinja:
+    """Tests for Jinja syntax."""
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"{% if [text](href) %}...{% endif %}",
+                id="jinja-block",
+            ),
+            pytest.param(
+                b"{{ [text](href) }}",
+                id="jinja-expr",
+            ),
+            pytest.param(
+                b"{# [text](href) #}",
+                id="jinja-comment",
+            ),
+        ],
+    )
+    def test_no_refs_inside_jinja(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestExclusions:
+    """Tests for further exclusions."""
+
+    def test_abbreviations(self) -> None:
+        md = b"*[abbr]: text\n"
+        refs = collect(md)
+        assert len(refs) == 0
+
+    @pytest.mark.parametrize(
+        "md",
+        [
+            pytest.param(
+                b"- [ ] task item\n",
+                id="checkbox",
+            ),
+            pytest.param(
+                b"- [x] done item\n",
+                id="checkbox, checked",
+            ),
+            pytest.param(
+                b"- [X] done item\n",
+                id="checkbox, checked, upper",
+            ),
+        ],
+    )
+    def test_tasklists(self, md: bytes) -> None:
+        refs = collect(md)
+        assert len(refs) == 0
+
+
+# ---------------------------------------------------------------------------
+
+
+class TestSpanOffsets:
+    """Tests for span offsets in links and references."""
+
+    def test_span(self) -> None:
+        md = b"[text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        assert refs[0].start == 0
+        assert refs[0].end == 12
+
+    def test_span_after(self) -> None:
+        md = b"content[text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        assert refs[0].start == 7
+        assert refs[0].end == 19
+
+    def test_span_after_lf(self) -> None:
+        md = b"content\n[text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        assert refs[0].start == 8
+        assert refs[0].end == 20
+
+    def test_span_after_crlf(self) -> None:
+        md = b"content\r\n[text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        assert refs[0].start == 9
+        assert refs[0].end == 21
+
+    def test_span_after_cr(self) -> None:
+        md = b"content\r[text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        assert refs[0].start == 8
+        assert refs[0].end == 20
+
+    def test_text_span(self) -> None:
+        md = b"[text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].text.start == 1
+        assert links[0].text.end == 5
+
+    def test_text_span_multibyte(self) -> None:
+        md = "[日本語](href)".encode()
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].text.start == 1
+        assert links[0].text.end == 10
+
+    def test_href_span(self) -> None:
+        md = b"[text](href)"
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].href.start == 7
+        assert links[0].href.end == 11
+
+    def test_href_span_multibyte(self) -> None:
+        md = "[text](例え.jp)".encode()
+        refs = collect(md)
+        assert len(refs) == 1
+
+        links = links_only(refs)
+        assert len(links) == 1
+        assert links[0].href.start == 7
+        assert links[0].href.end == 16
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+
+def collect(markdown: bytes, *, shift: int = 0) -> list[Reference]:
+    """Return all references as a plain list."""
+    return list(references(markdown, shift=shift))
+
+
+def text(markdown: bytes, span: Span) -> bytes:
+    """Return the slice that the given span covers."""
+    return markdown[span.start : span.end]
+
+
+# ---------------------------------------------------------------------------
+
+
+def links_only(refs: list) -> list[Link]:
+    """Filter to links or images only."""
+    return [ref for ref in refs if isinstance(ref, Link)]
+
+
+def link_refs_only(refs: list) -> list[LinkReference]:
+    """Filter to link or image references only."""
+    return [ref for ref in refs if isinstance(ref, LinkReference)]
+
+
+def link_defs_only(refs: list) -> list[LinkDefinition]:
+    """Filter to link or image definitions instances only."""
+    return [ref for ref in refs if isinstance(ref, LinkDefinition)]
+
+
+def footnote_refs_only(refs: list) -> list[FootnoteReference]:
+    """Filter to footnote references only."""
+    return [ref for ref in refs if isinstance(ref, FootnoteReference)]
+
+
+def footnote_defs_only(refs: list) -> list[FootnoteDefinition]:
+    """Filter to footnote definitions only."""
+    return [ref for ref in refs if isinstance(ref, FootnoteDefinition)]
diff --git a/python/zensical/collectors/exclusions.py b/python/zensical/collectors/exclusions.py
deleted file mode 100644
index 39f9909..0000000
--- a/python/zensical/collectors/exclusions.py
+++ /dev/null
@@ -1,212 +0,0 @@
-# Copyright (c) 2025-2026 Zensical and contributors
-
-# SPDX-License-Identifier: MIT
-# All contributions are certified under the DCO
-
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to
-# deal in the Software without restriction, including without limitation the
-# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
-# sell copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-
-from __future__ import annotations
-
-import re
-from typing import TYPE_CHECKING
-
-from zensical.utilities.span import Span
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-
-# ----------------------------------------------------------------------------
-# Constants
-# ----------------------------------------------------------------------------
-
-_RE = re.compile(
-    rb"""
-    # Escaped characters
-    (?P<escaped>
-        \\`                         # Backslash followed by any character
-    )
-    |
-    # Code blocks
-    #
-    #   ```python
-    #   ...
-    #   ```
-    #
-    (?P<code>
-        ^(?P<indent>[ \t]*)         # Capture leading indentation
-        (?P<fence>`{3,}|~{3,})      # Capture fence character and length
-        [^\r\n]*\r?\n               # Optional info string
-        .*?                         # Block content
-        ^[ \t]*(?P=fence)[`~]*      # Closing fence: same type, at least as long
-        [^\r\n]*(\r?\n|$)           # Optional trailing content
-    )
-    |
-    # HTML comments (block and inline)
-    #
-    #   <!-- Comment content -->
-    #
-    (?P<comment>
-        <!--                        # Opening delimiter
-        .*?                         # Comment content
-        -->                         # Closing delimiter
-    )
-    |
-    # HTML blocks (single-line)
-    #
-    #   <div>...</div>
-    #
-    (?P<html_inline>
-        ^<(?P<tag_inline>\w+)               # Opening block-level tag
-        (?P<attrs_inline>[ \t][^>]*)?       # Optional attributes
-        ></(?P=tag_inline)>[ \t]*(\r?\n|$)  # Immediate closing tag
-    )
-    |
-    # HTML blocks (multi-line)
-    #
-    #   <div>
-    #   ...
-    #   </div>
-    #
-    (?P<html>
-        ^<(?P<tag>\w+)              # Opening block-level tag
-        (?P<attrs>[ \t][^>]*)?      # Optional attributes (captured)
-        >[ \t]*\r?\n                # Close of tag, end of line
-        .*?                         # Block content
-        ^</(?P=tag)>[ \t]*\r?$      # Closing tag
-    )
-    |
-    # Block math:
-    #
-    #   $$
-    #   ...
-    #   $$
-    #
-    (?P<math_block>
-        ^[ \t]*\$\$[ \t]*\r?\n      # Opening $$ on its own line
-        .*?                         # Math content
-        ^[ \t]*\$\$[ \t]*\r?$       # Closing $$ on its own line
-    )
-    |
-    # Block math (alternate):
-    #
-    #   \[
-    #   ...
-    #   \]
-    #
-    (?P<math_block_alt>
-        ^[ \t]*\\\[[ \t]*\r?\n      # Opening \[ on its own line
-        .*?                         # Math content
-        ^[ \t]*\\\][ \t]*\r?$       # Closing \] on its own line
-    )
-    |
-    # Inline math:
-    #
-    #   $f(x)$
-    #
-    (?P<math_inline>
-        (?<!\$)\$(?![\s$])          # Opening $, not preceded/followed by $
-        (?-s:.*?)                   # Math content (same line only)
-        (?<![\s$])\$(?!\$)          # Closing $, not preceded by space or $
-    )
-    |
-    # Inline math (alternate):
-    #
-    #   \(f(x)\)
-    #
-    (?P<math_inline_alt>
-        \\\(                        # Opening \(
-        (?-s:.*?)                   # Math content (same line only)
-        \\\)                        # Closing \)
-    )
-    |
-    # Inline code blocks
-    #
-    #   `code`
-    #
-    (?P<code_inline>
-        (?P<ticks>`+)               # Opening backticks
-        .+?                         # Block content
-        (?P=ticks)                  # Closing backticks (matching)
-    )
-    |
-    # Jinja2 block tags:
-    #
-    #   {% if ... %}
-    #   {% for ... %}
-    #   {% endif %}
-    #
-    (?P<jinja_block>
-        \{%-?[ \t]*.*?[ \t]*-?%\}
-    )
-    |
-    # Jinja2 variable expressions:
-    #
-    #   {{ variable }}
-    #   {{ obj[key] }}
-    #   {{ func(arg) }}
-    #
-    (?P<jinja_expr>
-        \{\{-?[ \t]*.*?[ \t]*-?\}\}
-    )
-    |
-    # Jinja2 comments:
-    #
-    #   {# ... #}
-    #
-    (?P<jinja_comment>
-        \{#-?.*?-?#\}
-    )
-    """,
-    re.VERBOSE | re.MULTILINE | re.DOTALL,
-)
-"""
-Match regions that should be excluded from reference scanning.
-
-This includes fenced code blocks, inline code blocks, HTML comments, and HTML
-blocks without `markdown` attribute, as they may contain link-like patterns that
-should not be treated as references.
-"""
-
-# ----------------------------------------------------------------------------
-# Functions
-# ----------------------------------------------------------------------------
-
-
-def exclusions(content: bytes, shift: int = 0) -> Iterator[Span]:
-    """Scan Markdown and yield exclusions."""
-    for match in _RE.finditer(content):
-        if match.lastgroup != "html":
-            yield Span(shift + match.start(), shift + match.end())
-            continue
-
-        # In case this is a non-Markdown HTML block, we exclude the entire
-        # block, as it may contain link-like patterns that must be ignored
-        attrs = match.group("attrs") or b""
-        if b"markdown" not in attrs:
-            yield Span(shift + match.start(), shift + match.end())
-            continue
-
-        # Exclude opening tag line
-        end = content.index(b"\n", match.start()) + 1
-        yield Span(shift + match.start(), shift + end)
-
-        # Exclude closing tag line (cut from block), and recurse
-        start = end
-        end = content.rindex(b"\n", 0, match.end())
-        yield from exclusions(content[start:end], shift + start)
diff --git a/python/zensical/collectors/references.py b/python/zensical/collectors/references.py
deleted file mode 100644
index 869a629..0000000
--- a/python/zensical/collectors/references.py
+++ /dev/null
@@ -1,393 +0,0 @@
-# Copyright (c) 2025-2026 Zensical and contributors
-
-# SPDX-License-Identifier: MIT
-# All contributions are certified under the DCO
-
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to
-# deal in the Software without restriction, including without limitation the
-# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
-# sell copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from functools import partial
-from typing import TYPE_CHECKING, Literal, TypeAlias
-
-from zensical.collectors.exclusions import exclusions
-from zensical.utilities.span import Span
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-    from re import Match
-
-# ----------------------------------------------------------------------------
-# Classes
-# ----------------------------------------------------------------------------
-
-
-@dataclass
-class Link(Span):
-    """A link or image, e.g. `[text](href)` or `![alt](href)`."""
-
-    kind: Literal["link", "image", "autolink", "wikilink"]
-    """Discriminator identifying the variant."""
-
-    text: Span
-    """Span of visible link text (or image alt text)."""
-
-    href: Span
-    """Span of the link destination."""
-
-
-# ----------------------------------------------------------------------------
-
-
-@dataclass
-class LinkReference(Span):
-    """A link or image reference, e.g. `[text][id]` or `![alt][id]`."""
-
-    kind: Literal["link", "image"]
-    """Discriminator identifying the variant."""
-
-    text: Span
-    """Span of the visible link text (or image alt text)."""
-
-    id: Span
-    """Span of the link id."""
-
-
-@dataclass
-class LinkDefinition(Span):
-    """A link or image definition, e.g. `[id]: href`."""
-
-    id: Span
-    """Span of the link id."""
-
-    href: Span
-    """Span of the link destination."""
-
-
-# ----------------------------------------------------------------------------
-
-
-@dataclass
-class FootnoteReference(Span):
-    """A footnote reference, e.g. `[^id]`."""
-
-    id: Span
-    """Span of the footnote id."""
-
-
-@dataclass
-class FootnoteDefinition(Span):
-    """A footnote definition, e.g. `[^id]: body`."""
-
-    id: Span
-    """Span of the footnote id."""
-
-    body: Span
-    """Span of the footnote body, including multiline text."""
-
-
-# ----------------------------------------------------------------------------
-# Types
-# ----------------------------------------------------------------------------
-
-Reference: TypeAlias = (
-    Link
-    | LinkReference
-    | LinkDefinition
-    | FootnoteReference
-    | FootnoteDefinition
-)
-"""
-A reference extracted from Markdown.
-
-References might include inline links and images, reference-style link usages,
-reference definitions, footnote references, and footnote definitions. Each of
-those reference carries a source span covering the full matched text, plus
-additional metadata for the relevant subcomponents.
-"""
-
-# ----------------------------------------------------------------------------
-# Constants
-# ----------------------------------------------------------------------------
-
-_RE = re.compile(
-    rb"""
-    # Escaped characters:
-    #
-    #   \[ \] \! \*
-    #
-    (?P<escape>
-        \\[\[\]!*`]
-    )
-    |
-    # Task list checkbox:
-    #
-    #   - [ ] text
-    #   - [x] text
-    #   - [X] text
-    #
-    (?P<task>
-        ^[^\S\n]*[-*+][^\S\n]+\[[xX ]\]
-    )
-    |
-    # Footnote definition:
-    #
-    #   [^id]: body
-    #   [^id]:
-    #       body on next line
-    #
-    (?P<footdef>
-        ^[^\S\n]*\[\^(?P<footdef_id>[^\]]+)\]:[^\S\n]*
-        (?P<footdef_body>[^\n]*(?:\n[^\S\n]+[^\n]+)*)
-    )
-    |
-    # Link definition:
-    #
-    #   [id]: href
-    #   [id]: href "optional title"
-    #
-    (?P<linkdef>
-        ^[^\S\n]*\[(?P<linkdef_id>[^\]]+)\]:[^\S\n]*
-        (?P<linkdef_href>\S+)[^\n]*$
-    )
-    |
-    # Footnote reference:
-    #
-    #   [^id]
-    #
-    (?P<footref>
-        \[\^(?P<footref_id>[^\]]+)\]
-    )
-    |
-    # Wikilink:
-    #
-    #   [[text]]
-    #
-    (?P<wikilink>
-        \[\[(?P<wikilink_text>[^\]]+)\]\]
-    )
-    |
-    # Inline image:
-    #
-    #   ![alt](href)
-    #   ![alt](href "title")
-    #
-    (?P<image>
-        !\[(?P<image_alt>[^\]]*)\]
-        \((?P<image_href>[^)\s]+)[^)]*\)
-    )
-    |
-    # Image reference:
-    #
-    #   ![alt][id]
-    #   ![alt]\n[id]   (label on next line)
-    #   ![alt][]       (collapsed)
-    #   ![alt]         (shortcut)
-    #
-    (?P<imageref>
-        !\[(?P<imageref_alt>[^\]]*)\]
-        (?:[^\S\n]*\n?[^\S\n]*\[(?![\^])(?P<imageref_id>[^\]]*)\])?
-    )
-    |
-    # Inline link:
-    #
-    #   [text](href)
-    #   [text](href "title")
-    #
-    (?P<link>
-        \[(?P<link_text>[^\]]+)\]
-        \((?P<link_href>[^)\s]+)[^)]*\)
-    )
-    |
-    # Autolink:
-    #
-    #   <https://example.com>
-    #
-    (?P<autolink>
-        <(?P<autolink_href>https?://[^>]+)>
-    )
-    |
-    # Abbreviation definitions:
-    #
-    #   *[HTML]: Hyper Text Markup Language
-    #
-    (?P<abbr>
-        ^\*\[(?P<abbr_text>[^\]]+)\]:[^\n]*$
-    )
-    |
-    # Link reference:
-    #
-    #   [text][id]
-    #   [text]\n[id]   (label on next line)
-    #   [text][]       (collapsed)
-    #   [text]         (shortcut)
-    #
-    (?P<linkref>
-        \[(?P<linkref_text>[^\]]+)\]
-        (?:[^\S\n]*\n?[^\S\n]*\[(?![\^])(?P<linkref_id>[^\]]*)\])?
-    )
-    """,
-    re.VERBOSE | re.MULTILINE,
-)
-"""
-Match link-like constructs in Markdown.
-
-**Extraction and matching order**
-
-References are extracted via the compiled regex. The regex uses alternation
-with carefully ordered branches - specificity matters:
-
-- **Escaped characters** - `[` `]` `!` `*` (skipped, not treated as references)
-- **Task list checkbox** - `- [ ]` `- [x]` `- [X]`
-- **Footnote definition** - `[^id]: body` (block-level, can span lines)
-- **Link definition** - `[id]: href` (block-level, with optional title)
-- **Footnote reference** - `[^id]` (inline)
-- **Wikilink** - `[[target]]` (inline, standalone syntax)
-- **Inline image** - `![alt](href)` (inline)
-- **Image reference** - `![alt][id]`, `![alt][]`, `![alt]` (inline)
-- **Inline link** - `[text](href)` (inline)
-- **Autolink** - `<https://...>` (inline, angle-bracket syntax)
-- **Abbreviations** - `*[HTML]: Hyper Text Markup Language`
-- **Link reference** - `[text][id]`, `[text][]`, `[text]` (inline)
-
-**Why order matters**
-
-- Escaped characters are skipped and not treated as references.
-- Block-level definitions (footnote, link) are checked before inline patterns
-  to avoid overlaps with similar bracket syntax.
-- Images must be checked before links: `![alt](href)` starts with `!`, but
-  if not caught early, could conflict with `[text](href)` patterns.
-- Autolinks are more specific (`<...>`) and checked before generic reference
-  links (`[text][id]`).
-- Wikilinks (`[[...]]`) are unambiguous and can appear earlier.
-
-**Shortcut and collapsed references**
-
-Link and image references support three forms:
-
-- **Explicit**: `[text][id]` or `![alt][id]` - the id is explicit
-- **Collapsed**: `[text][]` or `![alt][]` - empty brackets, shortcut
-- **Shortcut**: `[text]` or `![alt]` - no second brackets, shortcut
-
-In collapsed and shortcut forms, the reference id defaults to the visible text.
-"""
-
-# ----------------------------------------------------------------------------
-# Functions
-# ----------------------------------------------------------------------------
-
-
-def references(markdown: bytes, shift: int = 0) -> Iterator[Reference]:
-    """Scan Markdown and yield all references.
-
-    Performs a single left-to-right pass over the given Markdown by using an
-    alternation regex, yielding one `Reference` per match in source order. No
-    state is carried between matches. Results can be collected into a list
-    or processed lazily.
-    """
-    exclude = iter(exclusions(markdown))
-    current = next(exclude, None)
-    for match in _RE.finditer(markdown):
-        kind = match.lastgroup
-
-        # Extract the start and end positions of the full match, and build a
-        # partial function to extract spans from named capture groups
-        start, end = shift + match.start(), shift + match.end()
-        span = partial(_span, shift, match)
-
-        # Advance past exclusions that end before this match
-        while current and current.end <= start:
-            current = next(exclude, None)
-
-        # If the current exclusion covers the match, skip it
-        if current and (current.contains(start) or current.contains(end)):
-            continue
-
-        # Inline link
-        if kind == "link":
-            text, href = span("link_text"), span("link_href")
-            yield Link(start, end, "link", text, href)
-
-        # Inline image
-        elif kind == "image":
-            text, href = span("image_alt"), span("image_href")
-            yield Link(start, end, "image", text, href)
-
-        # Image reference
-        elif kind == "imageref":
-            text = span("imageref_alt")
-            id = _span_for_id(shift, match, "imageref_id") or text
-            yield LinkReference(start, end, "image", text, id)
-
-        # Link reference
-        elif kind == "linkref":
-            text = span("linkref_text")
-            id = _span_for_id(shift, match, "linkref_id") or text
-            yield LinkReference(start, end, "link", text, id)
-
-        # Link definition
-        elif kind == "linkdef":
-            id, href = span("linkdef_id"), span("linkdef_href")
-            yield LinkDefinition(start, end, id, href)
-
-        # Footnote reference
-        elif kind == "footref":
-            id = span("footref_id")
-            yield FootnoteReference(start, end, id)
-
-        # Footnote definition
-        elif kind == "footdef":
-            id, body = span("footdef_id"), span("footdef_body")
-            yield FootnoteDefinition(start, end, id, body)
-
-            # Recurse into footnote body to extract nested references, shifting
-            # the content to account for the position of the Markdown body
-            yield from references(
-                markdown[body.start : body.end], shift + body.start
-            )
-
-        # Wikilink
-        elif kind == "wikilink":
-            text = span("wikilink_text")
-            yield Link(start, end, "wikilink", text, text)
-
-        # Autolink
-        elif kind == "autolink":
-            href = span("autolink_href")
-            yield Link(start, end, "autolink", href, href)
-
-
-# ----------------------------------------------------------------------------
-
-
-def _span(shift: int, match: Match[bytes], name: str) -> Span:
-    """Build a span for a named capture group within a match."""
-    start, end = match.start(name), match.end(name)
-    return Span(shift + start, shift + end)
-
-
-def _span_for_id(shift: int, match: Match[bytes], name: str) -> Span | None:
-    """Build an id span for a named capture group within a match."""
-    if match.group(name):
-        return _span(shift, match, name)
-
-    # Return nothing
-    return None
diff --git a/python/zensical/collectors/references/__init__.py b/python/zensical/collectors/references/__init__.py
new file mode 100644
index 0000000..135e990
--- /dev/null
+++ b/python/zensical/collectors/references/__init__.py
@@ -0,0 +1,59 @@
+# Copyright (c) 2025-2026 Zensical and contributors
+
+# SPDX-License-Identifier: MIT
+# All contributions are certified under the DCO
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from zensical.collectors.references.cursor import Cursor, _scan
+from zensical.collectors.references.types import (
+    FootnoteDefinition,
+    FootnoteReference,
+    Link,
+    LinkDefinition,
+    LinkReference,
+    Reference,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+__all__ = [
+    "FootnoteDefinition",
+    "FootnoteReference",
+    "Link",
+    "LinkDefinition",
+    "LinkReference",
+    "Reference",
+    "references",
+]
+
+# ---------------------------------------------------------------------------
+# Functions
+# ---------------------------------------------------------------------------
+
+
+def references(markdown: bytes, shift: int = 0) -> Iterator[Reference]:
+    """Scan Markdown and yield references."""
+    cursor = Cursor(markdown, shift)
+    yield from _scan(cursor)
diff --git a/python/zensical/collectors/references/cursor.py b/python/zensical/collectors/references/cursor.py
new file mode 100644
index 0000000..86621f8
--- /dev/null
+++ b/python/zensical/collectors/references/cursor.py
@@ -0,0 +1,1483 @@
+# Copyright (c) 2025-2026 Zensical and contributors
+
+# SPDX-License-Identifier: MIT
+# All contributions are certified under the DCO
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from markdown.util import BLOCK_LEVEL_ELEMENTS
+
+from zensical.collectors.references.types import (
+    FootnoteDefinition,
+    FootnoteReference,
+    Link,
+    LinkDefinition,
+    LinkReference,
+    Reference,
+)
+from zensical.utilities.span import Span
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# fmt: off
+
+# Whitespace
+_NL         = ord(b"\n")
+_CR         = ord(b"\r")
+_SPACE      = ord(b" ")
+_TAB        = ord(b"\t")
+
+# Brackets and delimiters
+_LBRACKET   = ord(b"[")
+_RBRACKET   = ord(b"]")
+_LPAREN     = ord(b"(")
+_RPAREN     = ord(b")")
+_LANGLE     = ord(b"<")
+_RANGLE     = ord(b">")
+_LCURLY     = ord(b"{")
+_RCURLY     = ord(b"}")
+
+# Punctuation
+_BACKSLASH  = ord(b"\\")
+_BACKTICK   = ord(b"`")
+_TILDE      = ord(b"~")
+_BANG       = ord(b"!")
+_HASH       = ord(b"#")
+_STAR       = ord(b"*")
+_DASH       = ord(b"-")
+_PLUS       = ord(b"+")
+_DOLLAR     = ord(b"$")
+_PERCENT    = ord(b"%")
+_CARET      = ord(b"^")
+_COLON      = ord(b":")
+_EQUALS     = ord(b"=")
+_SLASH      = ord(b"/")
+_QUOTE      = ord(b'"')
+_SQUOTE     = ord(b"'")
+_UNDERSCORE = ord(b"_")
+_PIPE       = ord(b"|")
+_DOT        = ord(b".")
+
+# Sets
+_WHITESPACE   = frozenset({_SPACE, _TAB})
+_QUOTES       = frozenset({_QUOTE, _SQUOTE})
+_MARKERS      = frozenset({_DASH, _STAR, _PLUS})
+_ESCAPABLE    = frozenset({
+    _LBRACKET, _RBRACKET, _LPAREN, _RPAREN, _LANGLE, _RANGLE,
+    _LCURLY,   _RCURLY,   _BANG,   _STAR,   _HASH,   _TILDE,
+    _DOLLAR,   _BACKSLASH,_BACKTICK,_DASH,  _PLUS,   _CARET,
+    _COLON,    _QUOTE,    _SQUOTE, _PIPE,   _UNDERSCORE, _DOT, _PERCENT,
+})
+_BLOCK_TAGS: frozenset[bytes] = frozenset(
+    tag.encode() for tag in BLOCK_LEVEL_ELEMENTS
+)
+
+# fmt: on
+
+# ---------------------------------------------------------------------------
+# Classes
+# ---------------------------------------------------------------------------
+
+
+class Cursor:
+    """Cursor over a `bytes` buffer.
+
+    The cursor tracks:
+
+    * `pos` - current byte offset (absolute, i.e. includes `shift`).
+    * `col` - column within the current line (0-based, reset on newline).
+    * `data` - the underlying byte buffer.
+    * `shift` - offset added to all emitted spans.
+    """
+
+    __slots__ = ("col", "data", "end", "pos", "shift")
+
+    def __init__(self, data: bytes, shift: int = 0) -> None:
+        self.data = data
+        self.end = len(data)
+        self.pos = 0
+        self.col = 0
+        self.shift = shift
+
+    def at_line_start(self) -> bool:
+        """Return whether the cursor is at the start of a line."""
+        return self.col == 0 or self._is_blank_prefix()
+
+    def peek(self, offset: int = 0) -> int:
+        """Return the byte at the current position plus the given offset."""
+        i = self.pos + offset
+        if i < self.end:
+            return self.data[i]
+        return -1
+
+    def advance(self, n: int = 1) -> None:
+        """Advance the cursor by `n` bytes."""
+        for _ in range(n):
+            if self.pos < self.end:
+                if self.data[self.pos] == _NL:
+                    self.col = 0
+                else:
+                    self.col += 1
+                self.pos += 1
+
+    def span(self, start: int, end: int) -> Span:
+        """Create a `Span` in the outer coordinate system."""
+        return Span(self.shift + start, self.shift + end)
+
+    def _is_blank_prefix(self) -> bool:
+        """Return whether there's only whitespace before the cursor."""
+        i = self.pos - 1
+        while i >= 0 and self.data[i] != _NL:
+            if self.data[i] not in _WHITESPACE:
+                return False
+            i -= 1
+        return True
+
+
+# ---------------------------------------------------------------------------
+# Functions
+# ---------------------------------------------------------------------------
+
+
+def _scan(cursor: Cursor) -> Iterator[Reference]:
+    """Yield references."""
+    while cursor.pos < cursor.end:
+        char = cursor.data[cursor.pos]
+
+        # Escaped character or math
+        if char == _BACKSLASH:
+            next = cursor.peek(1)
+
+            # Math: \[...\]
+            if next == _LBRACKET:
+                end = _scan_math_block_brackets(cursor)
+                if end is not None:
+                    cursor.advance(end - cursor.pos)
+                    continue
+
+            # Math: \(...\)
+            if next == _LPAREN:
+                end = _scan_math_inline_parens(cursor)
+                if end is not None:
+                    cursor.advance(end - cursor.pos)
+                    continue
+
+            # Escapable character
+            if next in _ESCAPABLE:
+                cursor.advance(2)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Code block: ```...``` or `...`
+        if char == _BACKTICK:
+            if cursor.at_line_start():
+                end = _scan_fenced_code(cursor, _BACKTICK)
+                if end is not None:
+                    cursor.advance(end - cursor.pos)
+                    continue
+
+            # Inline code: `...`
+            end = _scan_inline_code(cursor)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Code block: ~~~...~~~
+        if char == _TILDE and cursor.at_line_start():
+            end = _scan_fenced_code(cursor, _TILDE)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Math: $$...$$ or $...$
+        if char == _DOLLAR:
+            if cursor.peek(1) == _DOLLAR:
+                end = _scan_math_block(cursor)
+                if end is not None:
+                    cursor.advance(end - cursor.pos)
+                    continue
+
+            # Math: $...$
+            end = _scan_math_inline(cursor)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # HTML or autolink
+        if char == _LANGLE:
+            # HTML comment: <!-- ... -->
+            end = _scan_html_comment(cursor)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # HTML block: <tag>...</tag>
+            if cursor.at_line_start():
+                start = cursor.pos
+                end = _scan_html_block(cursor)
+                if end is not None:
+                    yield from _scan_html_links(
+                        Cursor(cursor.data[start:end], cursor.shift + start)
+                    )
+                    cursor.advance(end - cursor.pos)
+                    continue
+
+            # HTML link: <a href="..."> or <img src="...">
+            result = _scan_html_tag(cursor)
+            if result is not None:
+                end, refs = result
+                yield from refs
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # Autolink: <http://example.com>
+            ref = _scan_autolink(cursor)
+            if ref is not None:
+                yield ref
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Jinja expression: {{...}} or {%...%} or {#...#}
+        if char == _LCURLY:
+            end = _scan_jinja(cursor)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Exclamation mark - images (inline and reference)
+        if char == _BANG and cursor.peek(1) == _LBRACKET:
+            ref = _scan_image_or_image_ref(cursor)
+            if ref is not None:
+                yield ref
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Link or footnote
+        if char == _LBRACKET:
+            # Wikilink: [[target]]
+            if cursor.peek(1) == _LBRACKET:
+                ref = _scan_wikilink(cursor)
+                if ref is not None:
+                    yield ref
+                    continue
+
+            # Footnote reference or definition: [^id] or [^id]: body
+            if cursor.peek(1) == _CARET:
+                result = _scan_footnote_ref_or_def(cursor)
+                if result is not None:
+                    if isinstance(result, Reference):
+                        yield result
+                    else:
+                        yield from result
+                    continue
+
+            # Link definition: [id]: href
+            if cursor.at_line_start():
+                ref = _scan_link_def(cursor)
+                if ref is not None:
+                    yield ref
+                    continue
+
+            # Link or link reference: [text](href) or [text][id] or [text]
+            ref = _scan_link_or_link_ref(cursor)
+            if ref is not None:
+                yield ref
+
+                # References inside link text: [![alt](img)](href)
+                yield from _scan_refs(cursor, ref)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Abbreviation definition: *[abbr]: body
+        if (
+            char == _STAR
+            and cursor.at_line_start()
+            and cursor.peek(1) == _LBRACKET
+        ):
+            end = _scan_abbreviation(cursor)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # List marker at line start - tasklist checkbox
+        if char in _MARKERS and cursor.at_line_start():
+            end = _scan_tasklist_checkbox(cursor)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+                continue
+
+            # Literal
+            cursor.advance(1)
+            continue
+
+        # Literal
+        cursor.advance(1)
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_link_or_link_ref(cursor: Cursor) -> Link | LinkReference | None:
+    """Scan for link or link reference.
+
+    This function attempts to parse a link or link reference, since both start
+    with `[` and have the same link text syntax. If successful, it returns a
+    `Link` if an href is found in parentheses, or a `LinkReference` if an
+    optional id is found in brackets, otherwise it returns `None`.
+    """
+    start = cursor.pos
+    if cursor.data[start] != _LBRACKET:
+        return None
+
+    # Consume link text
+    text = _scan_link_text(cursor, start + 1)
+    if text is None:
+        return None
+
+    # Consume link href in parenthesis, if present
+    end = text.end - cursor.shift + 1
+    if end < cursor.end and cursor.data[end] == _LPAREN:
+        result = _scan_link_href(cursor, end)
+        if result is not None:
+            href, end = result
+
+            # Advance cursor and return link
+            cursor.advance(end - start)
+            return Link(
+                cursor.shift + start,
+                cursor.shift + end,
+                "link",
+                text,
+                href,
+            )
+
+    # Consume link id
+    id, end = _scan_link_id(cursor, end)
+
+    # Advance cursor and return link reference
+    cursor.advance(end - start)
+    return LinkReference(
+        cursor.shift + start,
+        cursor.shift + end,
+        "link",
+        text,
+        id or text,
+    )
+
+
+def _scan_link_def(cursor: Cursor) -> LinkDefinition | None:
+    """Scan for link definition."""
+    start = cursor.pos
+
+    # Skip if there're more than four spaces of indentation
+    if cursor.col > 3:  # noqa: PLR2004
+        return None
+
+    # Consume link id
+    id, end = _scan_link_id(cursor, start)
+    if id is None:
+        return None
+
+    # Skip if at end of line or not followed by colon
+    if end >= cursor.end or cursor.data[end] != _COLON:
+        return None
+
+    # Skip whitespace and consume angle-bracket href, if present
+    end = _skip_whitespace(cursor, end + 1)
+    if end < cursor.end and cursor.data[end] == _LANGLE:
+        result = _scan_link_href_in_angle_brackets(cursor, end)
+        if result is not None:
+            href, end = result
+            while end < cursor.end and cursor.data[end] != _NL:
+                end += 1
+
+            # Advance cursor and return link definition
+            cursor.advance(end - start)
+            return LinkDefinition(
+                cursor.shift + start,
+                cursor.shift + end,
+                id,
+                href,
+            )
+
+    # Consume link href until whitespace or quote
+    begin = end
+    while end < cursor.end:
+        if cursor.data[end] in (_SPACE, _TAB, _NL, _CR, _QUOTE):
+            break
+
+        # Literal
+        end += 1
+
+    # Skip if we didn't find an href
+    href = cursor.span(begin, end)
+    if href.start == href.end:
+        return None
+
+    # Advance cursor and return link definition
+    end = _skip_whitespace_newline(cursor, end)
+    cursor.advance(end - start)
+    return LinkDefinition(
+        cursor.shift + start,
+        cursor.shift + end,
+        id,
+        href,
+    )
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_link_text(cursor: Cursor, start: int) -> Span | None:
+    """Scan for link text, handling nested brackets and escapes.
+
+    This function assumes the opening `[` has already been consumed and starts
+    scanning from the first character of the link text. It returns the span of
+    the link text (i.e. the content between the outermost brackets) or `None`
+    if no matching closing `]` is found.
+    """
+    depth = 1
+
+    # Start after the opening [
+    end = start
+    while end < cursor.end:
+        char = cursor.data[end]
+
+        # Skip escaped character
+        if char == _BACKSLASH and end + 1 < cursor.end:
+            end += 2
+            continue
+
+        # Increment depth
+        if char == _LBRACKET:
+            depth += 1
+
+        # Decrement depth, terminate if we reach 0
+        elif char == _RBRACKET:
+            depth -= 1
+
+            # Terminate if brackets are balanced
+            if depth == 0:
+                return cursor.span(start, end)
+
+        # Literal
+        end += 1
+
+    # Unmatched
+    return None
+
+
+def _scan_link_href(cursor: Cursor, start: int) -> tuple[Span, int] | None:
+    """Scan for link href, handling nested parenthesis and escapes."""
+    if cursor.data[start] != _LPAREN:
+        return None
+
+    # Skip whitespace and consume angle-bracket href, if present
+    end = _skip_whitespace(cursor, start + 1)
+    if end < cursor.end and cursor.data[end] == _LANGLE:
+        result = _scan_link_href_in_angle_brackets(cursor, end)
+        if result is not None:
+            href, pos = result
+
+            # Skip whitespace and return link if we're at the title or end
+            pos = _skip_whitespace_newline(cursor, pos)
+            if pos < cursor.end and cursor.data[pos] == _QUOTE:
+                while pos < cursor.end and cursor.data[pos] != _RPAREN:
+                    if cursor.data[pos] == _NL:
+                        return None
+
+                    # Literal
+                    pos += 1
+
+            # Terminate if we found a closing )
+            if pos < cursor.end and cursor.data[pos] == _RPAREN:
+                return href, pos + 1
+
+    # Start after the opening (
+    depth = 0
+    while end < cursor.end:
+        char = cursor.data[end]
+
+        # Skip escaped character
+        if char == _BACKSLASH and end + 1 < cursor.end:
+            end += 2
+            continue
+
+        # Increment depth
+        if char == _LPAREN:
+            depth += 1
+
+        # Decrement depth, terminate if we reach 0
+        elif char == _RPAREN:
+            if depth == 0:
+                break
+            depth -= 1
+
+        # Terminate if we reach quote and trim excess whitespace
+        elif char in _QUOTES:
+            while cursor.data[end - 1] in _WHITESPACE:
+                end -= 1
+            break
+
+        # Literal
+        end += 1
+
+    # Skip optional title and whitespace
+    href = cursor.span(start + 1, end)
+    while end < cursor.end and cursor.data[end] != _RPAREN:
+        if cursor.data[end] == _NL:
+            return None
+
+        # Literal
+        end += 1
+
+    # Terminate if we found a closing )
+    if end < cursor.end:
+        return href, end + 1
+
+    # Unmatched
+    return None
+
+
+def _scan_link_href_in_angle_brackets(
+    cursor: Cursor, end: int
+) -> tuple[Span, int] | None:
+    """Scan for link href in angle brackets."""
+    end += 1
+
+    # Scan until > or end of line
+    start = end
+    while (
+        end < cursor.end
+        and cursor.data[end] != _RANGLE
+        and cursor.data[end] != _NL
+    ):
+        end += 1
+
+    # Skip closing >, or abort if we reached end of line
+    if end < cursor.end and cursor.data[end] == _RANGLE:
+        return cursor.span(start, end), end + 1
+
+    # Unmatched
+    return None
+
+
+def _scan_link_id(cursor: Cursor, pos: int) -> tuple[Span | None, int]:
+    """Scan for link id.
+
+    Link ids occur in two possible contexts: link references `[text][id]` and
+    link definitions `[id]: href`. If no id is found, this function returns
+    `None`. The returned position either equals the given position, if no id
+    was found, or the position immediately after the closing `]` of the id.
+    """
+    start = _skip_whitespace_newline(cursor, pos)
+    if start == cursor.end:
+        return None, start
+
+    # Consume id, but only if it's not a footnote or wikilink
+    if cursor.data[start] == _LBRACKET and (
+        start + 1 >= cursor.end
+        or cursor.data[start + 1] not in (_CARET, _LBRACKET)
+    ):
+        result = _scan_link_id_identifier(cursor, start + 1)
+        if result is not None:
+            return result
+
+    # Unmatched
+    return None, start
+
+
+def _scan_link_id_identifier(
+    cursor: Cursor, start: int
+) -> tuple[Span | None, int] | None:
+    """Scan for link id identifier."""
+    end = start
+    while end < cursor.end:
+        char = cursor.data[end]
+
+        # Skip escaped character
+        if char == _BACKSLASH and end + 1 < cursor.end:
+            end += 2
+            continue
+
+        # Terminate if we reach a [, as nested brackets are not allowed
+        if char == _LBRACKET:
+            return None
+
+        # Terminate if we reach a closing ]
+        if char == _RBRACKET:
+            if end == start:
+                return None, end + 1
+
+            # Skip closing ] and return id
+            return cursor.span(start, end), end + 1
+
+        # Literal
+        end += 1
+
+    # Unmatched
+    return None
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_image_or_image_ref(cursor: Cursor) -> Link | LinkReference | None:
+    """Scan for image or image reference.
+
+    This function first attempts to parse a link or link reference, since both
+    start with `[` and have the same link text syntax.
+    """
+    start = cursor.pos
+    if cursor.data[start] != _BANG:
+        return None
+    if cursor.data[start + 1] != _LBRACKET:
+        return None
+
+    # Consume image alt
+    text = _scan_link_text(cursor, start + 2)
+    if text is None:
+        return None
+
+    # Consume image href in parenthesis, if present
+    end = text.end - cursor.shift + 1
+    if end < cursor.end and cursor.data[end] == _LPAREN:
+        result = _scan_link_href(cursor, end)
+        if result is not None:
+            href, end = result
+
+            # Advance cursor and return link
+            cursor.advance(end - start)
+            return Link(
+                cursor.shift + start,
+                cursor.shift + end,
+                "image",
+                text,
+                href,
+            )
+
+    # Consume image id
+    id, end = _scan_link_id(cursor, end)
+
+    # Advance cursor and return image reference
+    cursor.advance(end - start)
+    return LinkReference(
+        cursor.shift + start,
+        cursor.shift + end,
+        "image",
+        text,
+        id or text,
+    )
+
+
+def _scan_refs(
+    cursor: Cursor, ref: Link | LinkReference
+) -> Iterator[Reference]:
+    """Scan for inner images inside the given link.
+
+    This function is called after successfully parsing a link or link reference.
+    It scans the link text for any inner images (inline or reference) and yields
+    them as `Link` objects with kind `"image"`. This allows us to capture image
+    references inside link texts.
+    """
+    if ref.kind != "link":
+        return
+
+    # Calculate the absolute positions of the link text
+    start = ref.text.start - cursor.shift
+    end = ref.text.end - cursor.shift
+
+    # Scan the link or link reference text for inner images
+    yield from _scan(Cursor(cursor.data[start:end], ref.text.start))
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_autolink(cursor: Cursor) -> Link | None:
+    """Scan for autolink."""
+    start = cursor.pos
+    if cursor.data[start] != _LANGLE:
+        return None
+
+    # Skip if schema doesn't match http:// or https://
+    schema = cursor.data[start + 1 : start + 9].lower()
+    if schema.startswith((b"https://", b"http://")):
+        result = _scan_link_href_in_angle_brackets(cursor, start)
+        if result is not None:
+            href, end = result
+
+            # Advance cursor and return link
+            cursor.advance(end - start)
+            return Link(
+                cursor.shift + start,
+                cursor.shift + end,
+                "autolink",
+                href,
+                href,
+            )
+
+    # Unmatched
+    return None
+
+
+def _scan_wikilink(cursor: Cursor) -> Link | None:
+    """Scan for wikilink.
+
+    This function attempts to parse a wikilink, which starts with `[[` and ends
+    with `]]`. The content between the brackets is the link target, which is
+    also used as the link text. If the wikilink is followed by an `[id]`, it's
+    treated as a link reference, to align with Python Markdown.
+    """
+    start = cursor.pos
+    if cursor.data[start] != _LBRACKET or cursor.data[start + 1] != _LBRACKET:
+        return None
+
+    # Consume wikilink target
+    end = _find_bracket(cursor, start + 2)
+    if (
+        end + 1 >= cursor.end
+        or cursor.data[end] != _RBRACKET
+        or cursor.data[end + 1] != _RBRACKET
+    ):
+        return None
+
+    # Skip if we didn't find a target
+    text = cursor.span(start + 2, end)
+    if text.start == text.end:
+        return None
+
+    # Skip closing brackets
+    end += 2
+
+    # If the wikilink is followed by an [id], it's a regular link, LOL
+    begin = _skip_whitespace_newline(cursor, end)
+    if (
+        begin < cursor.end
+        and cursor.data[begin] == _LBRACKET
+        and (begin + 1 >= cursor.end or cursor.data[begin + 1] != _CARET)
+    ):
+        close = _find_bracket(cursor, begin + 1)
+        if close < cursor.end and cursor.data[close] == _RBRACKET:
+            return None
+
+    # Advance cursor and return link
+    cursor.advance(end - start)
+    return Link(
+        cursor.shift + start,
+        cursor.shift + end,
+        "wikilink",
+        text,
+        text,
+    )
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_footnote_ref_or_def(
+    cursor: Cursor,
+) -> Reference | Iterator[Reference] | None:
+    """Scan for footnote reference or definition."""
+    start = cursor.pos
+    if cursor.data[start] != _LBRACKET or cursor.data[start + 1] != _CARET:
+        return None
+
+    # Consume footnote id
+    end = _find_bracket(cursor, start + 2)
+    if end >= cursor.end or cursor.data[end] != _RBRACKET:
+        return None
+
+    # Skip if we didn't find an id
+    id = cursor.span(start + 2, end)
+    if id.start == id.end:
+        return None
+
+    # Validate id - non-empty, no internal spaces
+    text = cursor.data[id.start : id.end]
+    if _SPACE in text or _TAB in text:
+        return None
+
+    # Skip closing bracket
+    end += 1
+
+    # Consume footnote definition
+    if (
+        end < cursor.end
+        and cursor.data[end] == _COLON
+        and cursor.at_line_start()
+    ):
+        return _scan_footnote_def(cursor, id, end)
+
+    # Advance cursor and return link
+    cursor.advance(end - start)
+    return FootnoteReference(
+        cursor.shift + start,
+        cursor.shift + end,
+        id,
+    )
+
+
+def _scan_footnote_def(
+    cursor: Cursor,
+    id: Span,  # noqa: A002
+    end: int,
+) -> Iterator[Reference]:
+    """Scan for footnote definition and recurse into its body."""
+    start = cursor.pos
+
+    # Skip colon and leading whitespace to find body start
+    end = _skip_whitespace(cursor, end + 1)
+    body_start = end
+    end = _skip_line(cursor, end)
+
+    # Continuation lines: indented lines belong to the same definition
+    while end < cursor.end and cursor.data[end] in _WHITESPACE:
+        end = _skip_line(cursor, end)
+
+    # Trim trailing newlines from the body span
+    body_end = end
+    while body_end > body_start and cursor.data[body_end - 1] in (_NL, _CR):
+        body_end -= 1
+
+    # Build and emit the definition
+    body = cursor.span(body_start, body_end)
+
+    # Advance cursor and return footnote definition
+    cursor.advance(end - start)
+    yield FootnoteDefinition(
+        cursor.shift + start,
+        cursor.shift + end,
+        id,
+        body,
+    )
+
+    # Scan the footnote body for inner references
+    text = cursor.data[body_start:body_end]
+    yield from _scan(Cursor(text, cursor.shift + body_start))
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_fenced_code(cursor: Cursor, char: int) -> int | None:
+    """Scan for fenced code block using ``` or ~~~.
+
+    Follows Python Markdown's rules:
+
+    * The closing fence must be the **same character** as the opening fence
+      (backticks cannot close a tilde fence and vice versa).
+    * The closing fence must be **exactly** the same length as the opening
+      fence — longer or shorter fences do not close the block.
+    * An **unclosed** fence is not a code block; parsing continues normally
+      after the opening line.
+    """
+    pos = cursor.pos
+
+    # Compute length of opening fence
+    opening = 0
+    while pos < cursor.end and cursor.data[pos] == char:
+        opening += 1
+        pos += 1
+
+    # Skip if the fence is too short
+    if opening < 3:  # noqa: PLR2004
+        return None
+
+    # Skip to end of line and search for closing fence
+    pos = _skip_line(cursor, pos)
+    while pos < cursor.end:
+        start = _skip_whitespace(cursor, pos)
+
+        # Compute length of closing fence
+        end = start
+        while end < cursor.end and cursor.data[end] == char:
+            end += 1
+
+        # Skip to next line and terminate if we found a closing fence
+        if end - start == opening:
+            rest = _skip_whitespace(cursor, end)
+            if rest >= cursor.end or cursor.data[rest] == _NL:
+                return _skip_line(cursor, end)
+
+        # Skip to next line
+        pos = _skip_line(cursor, pos)
+
+    # Unmatched
+    return None
+
+
+def _scan_inline_code(cursor: Cursor) -> int | None:
+    """Scan for inline code block."""
+    pos = cursor.pos
+
+    # Count opening backticks
+    opening = 0
+    while pos < cursor.end and cursor.data[pos] == _BACKTICK:
+        opening += 1
+        pos += 1
+
+    # Skip if there are no backticks
+    if opening == 0:
+        return None
+
+    # Search for matching closing backticks
+    while pos < cursor.end:
+        if cursor.data[pos] == _BACKTICK:
+            end = pos
+
+            # Count closing backticks
+            while end < cursor.end and cursor.data[end] == _BACKTICK:
+                end += 1
+
+            # Terminate if we found matching closing backticks
+            if end - pos == opening:
+                return end
+            pos = end
+        else:
+            pos += 1
+
+    # Unmatched
+    return None
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_math_inline(cursor: Cursor) -> int | None:
+    """Scan for `$...$` math."""
+    end = cursor.pos
+    if end >= cursor.end and cursor.data[end] != _DOLLAR:
+        return None
+
+    # Skip opening $ and abort if it's followed by whitespace or another $
+    end += 1
+    if end >= cursor.end and (
+        cursor.data[end] in (_DOLLAR, _SPACE, _TAB, _NL, _CR)
+    ):
+        return None
+
+    # Scan for closing $
+    while end < cursor.end and cursor.data[end] != _NL:
+        if (
+            cursor.data[end] == _DOLLAR
+            # Closing $ must not be preceded by whitespace or $
+            and cursor.data[end - 1] not in (_SPACE, _TAB, _DOLLAR)
+            # Closing $ must not be followed by $ (would be part of $$)
+            and (end + 1 >= cursor.end or cursor.data[end + 1] != _DOLLAR)
+        ):
+            return end + 1
+
+        # Literal
+        end += 1
+
+    # Unmatched
+    return None
+
+
+def _scan_math_block(cursor: Cursor) -> int | None:
+    """Scan for `$$ ... $$` math, both single-line and multi-line."""
+    return _scan_math(cursor, b"$$", b"$$", multiline=True)
+
+
+def _scan_math_block_brackets(cursor: Cursor) -> int | None:
+    r"""Scan for `\[ ... \]` math, both single-line and multi-line."""
+    return _scan_math(cursor, b"\\[", b"\\]", multiline=True)
+
+
+def _scan_math_inline_parens(cursor: Cursor) -> int | None:
+    r"""Scan for `\( ... \)` math, only single-line."""
+    return _scan_math(cursor, b"\\(", b"\\)", multiline=False)
+
+
+def _scan_math(
+    cursor: Cursor, opening: bytes, closing: bytes, *, multiline: bool
+) -> int | None:
+    """Scan for opening and closing math delimiters."""
+    start = cursor.pos
+    if cursor.data[start : start + 2] != opening:
+        return None
+
+    # Consume opening delimiter and scan for closing delimiter
+    start += 2
+    while start < cursor.end:
+        if not multiline and cursor.data[start] == _NL:
+            return None
+
+        # Consume closing delimiter and return if we found it
+        if cursor.data[start : start + 2] == closing:
+            start += 2
+
+            # Skip optional whitespace and newlines after closing delimiter
+            if multiline:
+                return _skip_line_ending(cursor, start)
+
+            # Otherwise return immediately
+            return start
+
+        # Literal
+        start += 1
+
+    # Unmatched
+    return None
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_html_links(cursor: Cursor) -> Iterator[Link]:
+    """Scan for HTML src and href attributes to extract links."""
+    while cursor.pos < cursor.end:
+        # Skip HTML comments
+        if cursor.data[cursor.pos : cursor.pos + 4] == b"<!--":
+            end = _scan_html_comment(cursor)
+            if end is not None:
+                cursor.advance(end - cursor.pos)
+            else:
+                cursor.pos = cursor.end
+            continue
+
+        # Scan HTML tags for links
+        if cursor.data[cursor.pos] == _LANGLE:
+            result = _scan_html_tag(cursor)
+            if result is not None:
+                end, links = result
+                yield from links
+
+                # Skip links
+                cursor.advance(end - cursor.pos)
+                continue
+
+        # Literal
+        cursor.advance(1)
+
+
+def _scan_html_comment(cursor: Cursor) -> int | None:
+    """Scan for an HTML comment."""
+    pos = cursor.pos
+    if cursor.data[pos : pos + 4] != b"<!--":
+        return None
+
+    # Search for closing -->
+    pos = cursor.data.find(b"-->", pos + 4)
+    if pos == -1:
+        return None
+
+    # Skip past -->
+    return pos + 3
+
+
+def _scan_html_attrs(
+    cursor: Cursor, pos: int
+) -> tuple[int, dict[bytes, Span]] | None:
+    """Scans for HTML attributes."""
+    attrs: dict[bytes, Span] = {}
+    while pos < cursor.end and cursor.data[pos] != _RANGLE:
+        if cursor.data[pos] in (_SPACE, _TAB, _NL, _CR, _SLASH):
+            pos += 1
+            continue
+
+        # Skip if attribute name doesn't start with alpha, _, or :
+        if not (
+            _is_alpha(cursor.data[pos])
+            or cursor.data[pos] in (ord(b"_"), ord(b":"))
+        ):
+            pos += 1
+            continue
+
+        # Consume attribute name
+        start = pos
+        while pos < cursor.end and (
+            cursor.data[pos]
+            not in (_SPACE, _TAB, _NL, _CR, _RANGLE, _SLASH, _EQUALS)
+        ):
+            pos += 1
+
+        # Extract and canonicalize attribute name
+        name = cursor.data[start:pos].lower()
+
+        # Skip whitespace before =
+        while pos < cursor.end and cursor.data[pos] in (_SPACE, _TAB, _NL, _CR):
+            pos += 1
+
+        # Boolean attribute - record presence with empty span
+        if pos >= cursor.end or cursor.data[pos] != _EQUALS:
+            attrs[name] = cursor.span(pos, pos)
+            continue
+
+        # Skip = and whitespace after it
+        pos += 1
+        while pos < cursor.end and cursor.data[pos] in (_SPACE, _TAB, _NL, _CR):
+            pos += 1
+
+        # Quoted value
+        if pos < cursor.end and cursor.data[pos] in _QUOTES:
+            quote = cursor.data[pos]
+            start = pos + 1
+
+            # Scan until closing quote
+            pos += 1
+            while pos < cursor.end and cursor.data[pos] != quote:
+                pos += 1
+
+            # Extract attribute value and skip closing quote
+            attrs[name] = cursor.span(start, pos)
+            if pos < cursor.end:
+                pos += 1  # past closing quote
+
+        # Unquoted value
+        else:
+            start = pos
+            while pos < cursor.end and (
+                cursor.data[pos] not in (_SPACE, _TAB, _NL, _CR, _RANGLE)
+            ):
+                pos += 1
+
+            # Extract attribute value and skip closing quote
+            attrs[name] = cursor.span(start, pos)
+
+    # Unclosed tag
+    if pos >= cursor.end:
+        return None
+
+    # Skip past >
+    return pos + 1, attrs
+
+
+def _scan_html_tag(cursor: Cursor) -> tuple[int, list[Link]] | None:
+    """Scan for HTML opening tag, returning its end position and any links."""
+    if cursor.pos >= cursor.end or cursor.data[cursor.pos] != _LANGLE:
+        return None
+
+    # Closing tag - don't consume
+    end = cursor.pos + 1
+    if end < cursor.end and cursor.data[end] == _SLASH:
+        return None
+
+    # Must start with ASCII letter
+    if end >= cursor.end or not _is_alpha(cursor.data[end]):
+        return None
+
+    # Consume tag name
+    while end < cursor.end and (
+        _is_alnum(cursor.data[end]) or cursor.data[end] == _DASH
+    ):
+        end += 1
+
+    # Must be followed by whitespace, >, or /
+    if end >= cursor.end or (
+        cursor.data[end] not in (_SPACE, _TAB, _NL, _CR, _RANGLE, _SLASH)
+    ):
+        return None
+
+    # Parse attributes and extract links from src and href
+    result = _scan_html_attrs(cursor, end)
+    if result is not None:
+        pos, attrs = result
+
+        # Extract links from src and href attributes, if present
+        links: list[Link] = []
+        for key in (b"src", b"href"):
+            span = attrs.get(key)
+            if span is not None and span.start < span.end:
+                links.append(Link(span.start, span.end, "html", span, span))
+
+        # Skip past the end of the tag and return any links we found
+        return pos, links
+
+    # Unmatched
+    return None
+
+
+def _scan_html_block(cursor: Cursor) -> int | None:
+    """Consume an HTML block that does not carry a `markdown` attribute."""
+    if cursor.pos >= cursor.end or cursor.data[cursor.pos] != _LANGLE:
+        return None
+
+    # Consume tag name
+    pos = cursor.pos + 1
+    if pos >= cursor.end or not _is_alpha(cursor.data[pos]):
+        return None
+    start = pos
+    while pos < cursor.end and _is_alnum(cursor.data[pos]):
+        pos += 1
+
+    # Only block-level tags suppress Markdown parsing inside them
+    name = cursor.data[start:pos]
+    if name.lower() not in _BLOCK_TAGS:
+        return None
+    start = pos
+
+    # Parse opening tag attributes - must fit on a single line
+    result = _scan_html_attrs(cursor, pos)
+    if result is None:
+        return None
+
+    # Skip if there are newlines in the opening tag
+    pos, attrs = result
+    if b"\n" in cursor.data[start:pos]:
+        return None
+
+    # If markdown attribute is set to a valid value, the md_in_html extension
+    # will parse the block's content as Markdown — hand back to the main loop
+    span = attrs.get(b"markdown")
+    if span is not None:
+        value = cursor.data[span.start : span.end]
+        if value in (b"", b"1", b"block", b"span"):
+            return None
+
+    # Inline form: opening and closing tag on the same line
+    closing_tag = b"</" + name + b">"
+    eol = cursor.data.find(b"\n", pos)
+    if eol == -1:
+        eol = cursor.end
+
+    # Search for closing tag on the same line
+    close = cursor.data.find(closing_tag, pos, eol + 1)
+    if close != -1:
+        return _skip_line_ending(cursor, close + len(closing_tag))
+
+    # Multi-line form: require a newline (with optional trailing whitespace)
+    i = _skip_whitespace(cursor, pos)
+    if i >= cursor.end or cursor.data[i] not in (_NL, _CR):
+        return None
+    if (
+        cursor.data[i] == _CR
+        and i + 1 < cursor.end
+        and cursor.data[i + 1] == _NL
+    ):
+        i += 1
+    pos = i + 1
+
+    # Find </tag> at line start - using find is much faster than regex or manual
+    # parsing and is still efficient since we only search for the closing tag
+    while True:
+        pos = cursor.data.find(closing_tag, pos)
+        if pos == -1:
+            return None
+
+        # Search for closing tag
+        start = cursor.data.rfind(b"\n", 0, pos)
+        start = 0 if start == -1 else start + 1
+        if cursor.data[start:pos].strip() == b"":
+            return _skip_line_ending(cursor, pos + len(closing_tag))
+
+        # Continue
+        pos += 1
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_jinja(cursor: Cursor) -> int | None:
+    """Scan for Jinja2 syntax."""
+    start = cursor.pos
+    if start + 1 >= cursor.end:
+        return None
+
+    # Determine closing delimiter based on second character
+    char = cursor.data[start + 1]
+    if char == _PERCENT:
+        close = b"%}"
+    elif char == _LCURLY:
+        close = b"}}"
+    elif char == _HASH:
+        close = b"#}"
+    else:
+        return None
+
+    # Scan for closing delimiter, allowing newlines but not blank lines
+    end = start + 2
+    newlines = 0
+    while end < cursor.end:
+        char = cursor.data[end]
+
+        # Check for two consecutive newlines
+        if char == _NL:
+            newlines += 1
+
+            # Terminte if we encounter a blank line
+            if newlines == 2:  # noqa: PLR2004
+                return None
+        else:
+            newlines = 0
+
+        # Check for closing delimiter
+        if cursor.data[end : end + 2] == close:
+            return end + 2
+
+        # Literal
+        end += 1
+
+    # Unmatched
+    return None
+
+
+# ---------------------------------------------------------------------------
+
+
+def _scan_abbreviation(cursor: Cursor) -> int | None:
+    """Scan for abbreviations."""
+    start = cursor.pos
+    if cursor.data[start : start + 2] != b"*[":
+        return None
+
+    # Find closing ]
+    end = _find_bracket(cursor, start + 2)
+    if end >= cursor.end or cursor.data[end] != _RBRACKET:
+        return None
+
+    # Skip closing ] and find :
+    end += 1
+    if end >= cursor.end or cursor.data[end] != _COLON:
+        return None
+
+    # Skip to end of line
+    return _skip_line(cursor, end)
+
+
+def _scan_tasklist_checkbox(cursor: Cursor) -> int | None:
+    """Scan for tasklist checkbox."""
+    pos = _skip_whitespace(cursor, cursor.pos)
+    if pos >= cursor.end or cursor.data[pos] not in _MARKERS:
+        return None
+
+    # Skip list marker and following space
+    pos += 1
+    if pos >= cursor.end or cursor.data[pos] not in _WHITESPACE:
+        return None
+
+    # Skip whitespace before checkbox
+    pos = _skip_whitespace(cursor, pos)
+
+    # Skip valid checkbox values [ ], [x], and [X]
+    if pos + 2 >= cursor.end:
+        return None
+    if cursor.data[pos] != _LBRACKET:
+        return None
+    if cursor.data[pos + 1] not in (_SPACE, ord("x"), ord("X")):
+        return None
+    if cursor.data[pos + 2] != _RBRACKET:
+        return None
+
+    # Return position after checkbox
+    return pos + 3
+
+
+# ---------------------------------------------------------------------------
+
+
+def _skip_whitespace(cursor: Cursor, pos: int) -> int:
+    """Skip horizontal whitespace (spaces and tabs)."""
+    while pos < cursor.end and cursor.data[pos] in _WHITESPACE:
+        pos += 1
+    return pos
+
+
+def _skip_whitespace_newline(cursor: Cursor, pos: int) -> int:
+    """Skip trailing horizontal whitespace and at most one newline."""
+    pos = _skip_whitespace(cursor, pos)
+    if pos < cursor.end and cursor.data[pos] == _NL:
+        pos = _skip_whitespace(cursor, pos + 1)
+    return pos
+
+
+def _skip_line_ending(cursor: Cursor, pos: int) -> int:
+    """Skip trailing horizontal whitespace and an optional newline."""
+    while pos < cursor.end and cursor.data[pos] in _WHITESPACE:
+        pos += 1
+    if pos < cursor.end and cursor.data[pos] == _CR:
+        pos += 1
+    if pos < cursor.end and cursor.data[pos] == _NL:
+        pos += 1
+    return pos
+
+
+def _skip_line(cursor: Cursor, pos: int) -> int:
+    """Skip to the next line, consuming the newline."""
+    while pos < cursor.end and cursor.data[pos] != _NL:
+        pos += 1
+    if pos < cursor.end:
+        pos += 1
+    return pos
+
+
+def _find_bracket(cursor: Cursor, pos: int) -> int:
+    """Find the next `]` or newline."""
+    while (
+        pos < cursor.end
+        and cursor.data[pos] != _RBRACKET
+        and cursor.data[pos] != _NL
+    ):
+        pos += 1
+    return pos
+
+
+# ----------------------------------------------------------------------------
+
+
+def _is_alpha(byte: int) -> bool:
+    """Check if byte is ASCII letter."""
+    return (ord("A") <= byte <= ord("Z")) or (ord("a") <= byte <= ord("z"))
+
+
+def _is_alnum(byte: int) -> bool:
+    """Check if byte is ASCII letter or digit."""
+    return _is_alpha(byte) or (ord("0") <= byte <= ord("9"))
diff --git a/python/zensical/collectors/references/types.py b/python/zensical/collectors/references/types.py
new file mode 100644
index 0000000..bf019fd
--- /dev/null
+++ b/python/zensical/collectors/references/types.py
@@ -0,0 +1,118 @@
+# Copyright (c) 2025-2026 Zensical and contributors
+
+# SPDX-License-Identifier: MIT
+# All contributions are certified under the DCO
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from zensical.utilities.span import Span
+
+# ----------------------------------------------------------------------------
+# Classes
+# ----------------------------------------------------------------------------
+
+
+@dataclass
+class Link(Span):
+    """A link or image, e.g. `[text](href)` or `![alt](href)`."""
+
+    kind: Literal["link", "image", "autolink", "wikilink", "html"]
+    """Discriminator identifying the variant."""
+
+    text: Span
+    """Span of visible link text (or image alt text)."""
+
+    href: Span
+    """Span of the link destination."""
+
+
+# ----------------------------------------------------------------------------
+
+
+@dataclass
+class LinkReference(Span):
+    """A link or image reference, e.g. `[text][id]` or `![alt][id]`."""
+
+    kind: Literal["link", "image"]
+    """Discriminator identifying the variant."""
+
+    text: Span
+    """Span of the visible link text (or image alt text)."""
+
+    id: Span
+    """Span of the link id."""
+
+
+@dataclass
+class LinkDefinition(Span):
+    """A link or image definition, e.g. `[id]: href`."""
+
+    id: Span
+    """Span of the link id."""
+
+    href: Span
+    """Span of the link destination."""
+
+
+# ----------------------------------------------------------------------------
+
+
+@dataclass
+class FootnoteReference(Span):
+    """A footnote reference, e.g. `[^id]`."""
+
+    id: Span
+    """Span of the footnote id."""
+
+
+@dataclass
+class FootnoteDefinition(Span):
+    """A footnote definition, e.g. `[^id]: body`."""
+
+    id: Span
+    """Span of the footnote id."""
+
+    body: Span
+    """Span of the footnote body, including multiline text."""
+
+
+# ----------------------------------------------------------------------------
+# Types
+# ----------------------------------------------------------------------------
+
+Reference: TypeAlias = (
+    Link
+    | LinkReference
+    | LinkDefinition
+    | FootnoteReference
+    | FootnoteDefinition
+)
+"""
+A reference extracted from Markdown.
+
+References might include inline links and images, link references and link
+definitions, footnote references, and footnote definitions. Each of those
+reference carries a source span covering the full matched text, possibly with
+additional metadata for the relevant subcomponents.
+"""