refactor: Record heading titles alongside URLs

This change makes autorefs record heading titles alongside URLs, but doesn't actually change the rendering logic. This will be done in a later change that will rely on new title-related options.

Issue-33: #33

Author: pawamoy

src/mkdocs_autorefs/plugin.py

@@ -111,6 +111,7 @@ def __init__(self) -> None:
         # This logic unfolds in `_get_item_url`.
         self._primary_url_map: dict[str, list[str]] = {}
         self._secondary_url_map: dict[str, list[str]] = {}
+        self._title_map: dict[str, str] = {}
         self._abs_url_map: dict[str, str] = {}
         # YORE: Bump 2: Remove line.
         self._get_fallback_anchor: Callable[[str], tuple[str, ...]] | None = None
@@ -133,13 +134,22 @@ def get_fallback_anchor(self, value: Callable[[str], tuple[str, ...]] | None) ->
                 stacklevel=2,
             )
 
-    def register_anchor(self, page: str, identifier: str, anchor: str | None = None, *, primary: bool = True) -> None:
+    def register_anchor(
+        self,
+        page: str,
+        identifier: str,
+        anchor: str | None = None,
+        *,
+        title: str | None = None,
+        primary: bool = True,
+    ) -> None:
         """Register that an anchor corresponding to an identifier was encountered when rendering the page.
 
         Arguments:
             page: The relative URL of the current page. Examples: `'foo/bar/'`, `'foo/index.html'`
             identifier: The identifier to register.
             anchor: The anchor on the page, without `#`. If not provided, defaults to the identifier.
+            title: The title of the anchor (optional).
             primary: Whether this anchor is the primary one for the identifier.
         """
         page_anchor = f"{page}#{anchor or identifier}"
@@ -148,7 +158,8 @@ def register_anchor(self, page: str, identifier: str, anchor: str | None = None,
             if page_anchor not in url_map[identifier]:
                 url_map[identifier].append(page_anchor)
         else:
-            url_map[identifier] = [page_anchor]
+        if title and url not in self._title_map:
+            self._title_map[url] = title
 
     def register_url(self, identifier: str, url: str) -> None:
         """Register that the identifier should be turned into a link to this URL.
@@ -240,7 +251,7 @@ def get_item_url(
         from_url: str | None = None,
         # YORE: Bump 2: Remove line.
         fallback: Callable[[str], Sequence[str]] | None = None,
-    ) -> str:
+    ) -> tuple[str, str | None]:
         """Return a site-relative URL with anchor to the identifier, if it's present anywhere.
 
         Arguments:
@@ -252,11 +263,12 @@ def get_item_url(
         """
         # YORE: Bump 2: Replace `, fallback` with `` within line.
         url = self._get_item_url(identifier, from_url, fallback)
+        title = self._title_map.get(url) or None
         if from_url is not None:
             parsed = urlsplit(url)
             if not parsed.scheme and not parsed.netloc:
-                return relative_url(from_url, url)
-        return url
+                url = relative_url(from_url, url)
+        return url, title
 
     def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         """Instantiate our Markdown extension.
@@ -321,7 +333,7 @@ def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
             base_url: The base URL to use as a prefix for each anchor's relative URL.
             anchor: The anchor to process and to recurse on.
         """
-        self.register_anchor(base_url, anchor.id, primary=True)
+        self.register_anchor(base_url, anchor.id, title=anchor.title, primary=True)
         for child in anchor.children:
             self.map_urls(base_url, child)
 

src/mkdocs_autorefs/references.py

@@ -258,7 +258,7 @@ def relative_url(url_a: str, url_b: str) -> str:
 
 # YORE: Bump 2: Remove block.
 def _legacy_fix_ref(
-    url_mapper: Callable[[str], str],
+    url_mapper: Callable[[str], tuple[str, str | None]],
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]],
 ) -> Callable:
     """Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub).
@@ -287,7 +287,7 @@ def inner(match: Match) -> str:
         classes = (match["class"] or "").strip('"').split()
 
         try:
-            url = url_mapper(unescape(identifier))
+            url, _ = url_mapper(unescape(identifier))
         except KeyError:
             if kind == "autorefs-optional":
                 return title
@@ -364,7 +364,10 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
 _html_attrs_parser = _HTMLAttrsParser()
 
 
-def _find_url(identifiers: Iterable[str], url_mapper: Callable[[str], str]) -> str:
+def _find_url(
+    identifiers: Iterable[str],
+    url_mapper: Callable[[str], tuple[str, str | None]],
+) -> tuple[str, str | None]:
     for identifier in identifiers:
         try:
             return url_mapper(identifier)
@@ -374,7 +377,7 @@ def _find_url(identifiers: Iterable[str], url_mapper: Callable[[str], str]) -> s
 
 
 def fix_ref(
-    url_mapper: Callable[[str], str],
+    url_mapper: Callable[[str], tuple[str, str | None]],
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]],
 ) -> Callable:
     """Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub).
@@ -406,7 +409,7 @@ def inner(match: Match) -> str:
         identifiers = (identifier, slug) if slug else (identifier,)
 
         try:
-            url = _find_url(identifiers, url_mapper)
+            url, original_title = _find_url(identifiers, url_mapper)
         except KeyError:
             if optional:
                 log.debug("Unresolved optional cross-reference: %s", identifier)
@@ -436,7 +439,7 @@ def inner(match: Match) -> str:
 
 def fix_refs(
     html: str,
-    url_mapper: Callable[[str], str],
+    url_mapper: Callable[[str], tuple[str, str | None]],
     # YORE: Bump 2: Remove line.
     _legacy_refs: bool = True,  # noqa: FBT001, FBT002
 ) -> tuple[str, list[tuple[str, AutorefsHookInterface.Context | None]]]:
@@ -481,7 +484,7 @@ def run(self, root: Element) -> None:  # noqa: D102
             self._scan_anchors(root, pending_anchors)
             pending_anchors.flush()
 
-    def _scan_anchors(self, parent: Element, pending_anchors: _PendingAnchors) -> None:
+    def _scan_anchors(self, parent: Element, pending_anchors: _PendingAnchors, last_heading: str | None = None) -> None:
         for el in parent:
             if el.tag == "a":
                 # We found an anchor. Record its id if it has one.
@@ -490,23 +493,24 @@ def _scan_anchors(self, parent: Element, pending_anchors: _PendingAnchors) -> No
                 # If the element has text or a link, it's not an alias.
                 # Non-whitespace text after the element interrupts the chain, aliases can't apply.
                 if el.text or el.get("href") or (el.tail and el.tail.strip()):
-                    pending_anchors.flush()
+                    pending_anchors.flush(title=last_heading)
 
             elif el.tag == "p":
                 # A `p` tag is a no-op for our purposes, just recurse into it in the context
                 # of the current collection of anchors.
-                self._scan_anchors(el, pending_anchors)
+                self._scan_anchors(el, pending_anchors, last_heading)
                 # Non-whitespace text after the element interrupts the chain, aliases can't apply.
                 if el.tail and el.tail.strip():
                     pending_anchors.flush()
 
             elif el.tag in self._htags:
                 # If the element is a heading, that turns the pending anchors into aliases.
-                pending_anchors.flush(el.get("id"))
+                last_heading = el.text
+                pending_anchors.flush(el.get("id"), title=last_heading)
 
             else:
                 # But if it's some other interruption, flush anchors anyway as non-aliases.
-                pending_anchors.flush()
+                pending_anchors.flush(title=last_heading)
                 # Recurse into sub-elements, in a *separate* context.
                 self.run(el)
 
@@ -522,9 +526,9 @@ def __init__(self, plugin: AutorefsPlugin, current_page: str):
     def append(self, anchor: str) -> None:
         self.anchors.append(anchor)
 
-    def flush(self, alias_to: str | None = None) -> None:
+    def flush(self, alias_to: str | None = None, title: str | None = None) -> None:
         for anchor in self.anchors:
-            self.plugin.register_anchor(self.current_page, anchor, alias_to, primary=True)
+            self.plugin.register_anchor(self.current_page, anchor, alias_to, title=title, primary=True)
         self.anchors.clear()
 
 

tests/test_plugin.py

@@ -16,8 +16,8 @@ def test_url_registration() -> None:
     plugin.register_anchor(identifier="foo", page="foo1.html", primary=True)
     plugin.register_url(identifier="bar", url="https://example.org/bar.html")
 
-    assert plugin.get_item_url("foo") == "foo1.html#foo"
-    assert plugin.get_item_url("bar") == "https://example.org/bar.html"
+    assert plugin.get_item_url("foo") == ("foo1.html#foo", None)
+    assert plugin.get_item_url("bar") == ("https://example.org/bar.html", None)
     with pytest.raises(KeyError):
         plugin.get_item_url("baz")
 
@@ -28,8 +28,8 @@ def test_url_registration_with_from_url() -> None:
     plugin.register_anchor(identifier="foo", page="foo1.html", primary=True)
     plugin.register_url(identifier="bar", url="https://example.org/bar.html")
 
-    assert plugin.get_item_url("foo", from_url="a/b.html") == "../foo1.html#foo"
-    assert plugin.get_item_url("bar", from_url="a/b.html") == "https://example.org/bar.html"
+    assert plugin.get_item_url("foo", from_url="a/b.html") == ("../foo1.html#foo", None)
+    assert plugin.get_item_url("bar", from_url="a/b.html") == ("https://example.org/bar.html", None)
     with pytest.raises(KeyError):
         plugin.get_item_url("baz", from_url="a/b.html")
 
@@ -42,11 +42,11 @@ def test_url_registration_with_fallback() -> None:
     plugin.register_url(identifier="bar", url="https://example.org/bar.html")
 
     # URL map will be updated with baz -> foo1.html#foo
-    assert plugin.get_item_url("baz", fallback=lambda _: ("foo",)) == "foo1.html#foo"
+    assert plugin.get_item_url("baz", fallback=lambda _: ("foo",)) == ("foo1.html#foo", None)
     # as expected, baz is now known as foo1.html#foo
-    assert plugin.get_item_url("baz", fallback=lambda _: ("bar",)) == "foo1.html#foo"
+    assert plugin.get_item_url("baz", fallback=lambda _: ("bar",)) == ("foo1.html#foo", None)
     # unknown identifiers correctly fallback: qux -> https://example.org/bar.html
-    assert plugin.get_item_url("qux", fallback=lambda _: ("bar",)) == "https://example.org/bar.html"
+    assert plugin.get_item_url("qux", fallback=lambda _: ("bar",)) == ("https://example.org/bar.html", None)
 
     with pytest.raises(KeyError):
         plugin.get_item_url("foobar", fallback=lambda _: ("baaaa",))
@@ -60,7 +60,10 @@ def test_dont_make_relative_urls_relative_again() -> None:
     plugin.register_anchor(identifier="foo.bar.baz", page="foo/bar/baz.html", primary=True)
 
     for _ in range(2):
-        assert plugin.get_item_url("foo.bar.baz", from_url="baz/bar/foo.html") == "../../foo/bar/baz.html#foo.bar.baz"
+        assert plugin.get_item_url("foo.bar.baz", from_url="baz/bar/foo.html") == (
+            "../../foo/bar/baz.html#foo.bar.baz",
+            None,
+        )
 
 
 @pytest.mark.parametrize(

tests/test_references.py

@@ -65,8 +65,8 @@ def run_references_test(
     md = markdown.Markdown(extensions=[AutorefsExtension(), *extensions], extension_configs=extensions)
     content = md.convert(source)
 
-    def url_mapper(identifier: str) -> str:
-        return relative_url(from_url, url_map[identifier])
+    def url_mapper(identifier: str) -> tuple[str, str | None]:
+        return relative_url(from_url, url_map[identifier]), None
 
     actual_output, actual_unmapped = fix_refs(content, url_mapper)
     assert actual_output == output