refactor: Store actual page instance instead of URL in plugin's current_page attribute

We will need the page instance for the backlinks feature, to build breadcrumbs with titles and URLs of the parents of each backlink.

Author: pawamoy

src/mkdocs_autorefs/plugin.py

@@ -99,7 +99,7 @@ class AutorefsPlugin(BasePlugin[AutorefsConfig]):
     """
 
     scan_toc: bool = True
-    current_page: str | None = None
+    current_page: Page | None = None
     # YORE: Bump 2: Remove line.
     legacy_refs: bool = True
 
@@ -138,6 +138,8 @@ def __init__(self) -> None:
         self._abs_url_map: dict[str, str] = {}
         # YORE: Bump 2: Remove line.
         self._get_fallback_anchor: Callable[[str], tuple[str, ...]] | None = None
+        # YORE: Bump 2: Remove line.
+        self._url_to_page: dict[str, Page] = {}
 
         self._link_titles: bool | Literal["external"] = True
         self._strip_title_tags: bool = False
@@ -162,7 +164,7 @@ def get_fallback_anchor(self, value: Callable[[str], tuple[str, ...]] | None) ->
 
     def register_anchor(
         self,
-        page: str,
+        page: Page,
         identifier: str,
         anchor: str | None = None,
         *,
@@ -172,18 +174,26 @@ def register_anchor(
         """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'`
+            page: The page where the anchor was found.
             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}"
+        # YORE: Bump 2: Remove block.
+        if isinstance(page, str):
+            try:
+                page = self._url_to_page[page]
+            except KeyError:
+                page = self.current_page
+
+        url = f"{page.url}#{anchor or identifier}"
         url_map = self._primary_url_map if primary else self._secondary_url_map
         if identifier in url_map:
-            if page_anchor not in url_map[identifier]:
-                url_map[identifier].append(page_anchor)
+            if url not in url_map[identifier]:
+                url_map[identifier].append(url)
         else:
+            url_map[identifier] = [url]
         if title and url not in self._title_map:
             self._title_map[url] = title
 
@@ -345,7 +355,9 @@ def on_page_markdown(self, markdown: str, page: Page, **kwargs: Any) -> str:  #
             The same Markdown. We only use this hook to keep a reference to the current page URL,
                 used during Markdown conversion by the anchor scanner tree processor.
         """
-        self.current_page = page.url
+        # YORE: Bump 2: Remove line.
+        self._url_to_page[page.url] = page
+        self.current_page = page
         return markdown
 
     def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str:  # noqa: ARG002
@@ -364,24 +376,33 @@ def on_page_content(self, html: str, page: Page, **kwargs: Any) -> str:  # noqa:
         Returns:
             The same HTML. We only use this hook to map anchors to URLs.
         """
+        self.current_page = page
+        # Collect `std`-domain URLs.
         if self.scan_toc:
             log.debug("Mapping identifiers to URLs for page %s", page.file.src_path)
             for item in page.toc.items:
-                self.map_urls(page.url, item)
+                self.map_urls(page, item)
         return html
 
-    def map_urls(self, base_url: str, anchor: AnchorLink) -> None:
+    def map_urls(self, page: Page, anchor: AnchorLink) -> None:
         """Recurse on every anchor to map its ID to its absolute URL.
 
         This method populates `self._primary_url_map` by side-effect.
 
         Arguments:
-            base_url: The base URL to use as a prefix for each anchor's relative URL.
+            page: The page containing the anchors.
             anchor: The anchor to process and to recurse on.
         """
-        self.register_anchor(base_url, anchor.id, title=anchor.title, primary=True)
+        # YORE: Bump 2: Remove block.
+        if isinstance(page, str):
+            try:
+                page = self._url_to_page[page]
+            except KeyError:
+                page = self.current_page
+
+        self.register_anchor(page, anchor.id, title=anchor.title, primary=True)
         for child in anchor.children:
-            self.map_urls(base_url, child)
+            self.map_urls(page, child)
 
     @event_priority(-50)  # Late, after mkdocstrings has finished loading inventories.
     def on_env(self, env: Environment, /, *, config: MkDocsConfig, files: Files) -> Environment:  # noqa: ARG002

src/mkdocs_autorefs/references.py

@@ -542,7 +542,7 @@ def __init__(self, plugin: AutorefsPlugin, md: Markdown | None = None) -> None:
 
     def run(self, root: Element) -> None:  # noqa: D102
         if self.plugin.current_page is not None:
-            pending_anchors = _PendingAnchors(self.plugin, self.plugin.current_page)
+            pending_anchors = _PendingAnchors(self.plugin)
             self._scan_anchors(root, pending_anchors)
             pending_anchors.flush()
 
@@ -580,18 +580,18 @@ def _scan_anchors(self, parent: Element, pending_anchors: _PendingAnchors, last_
 class _PendingAnchors:
     """A collection of HTML anchors that may or may not become aliased to an upcoming heading."""
 
-    def __init__(self, plugin: AutorefsPlugin, current_page: str):
+    def __init__(self, plugin: AutorefsPlugin):
         self.plugin = plugin
-        self.current_page = current_page
         self.anchors: list[str] = []
 
     def append(self, anchor: str) -> None:
         self.anchors.append(anchor)
 
     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, title=title, primary=True)
-        self.anchors.clear()
+        if page := self.plugin.current_page:
+            for anchor in self.anchors:
+                self.plugin.register_anchor(page, anchor, alias_to, title=title, primary=True)
+            self.anchors.clear()
 
 
 @lru_cache

tests/helpers.py

@@ -0,0 +1,14 @@
+"""Helper functions for the tests."""
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File
+from mkdocs.structure.pages import Page
+
+
+def create_page(url: str) -> Page:
+    """Create a page with the given URL."""
+    return Page(
+        title=url,
+        file=File(url, "docs", "site", use_directory_urls=False),
+        config=MkDocsConfig(),
+    )

tests/test_plugin.py

@@ -11,12 +11,13 @@
 
 from mkdocs_autorefs.plugin import AutorefsConfig, AutorefsPlugin
 from mkdocs_autorefs.references import fix_refs
+from tests.helpers import create_page
 
 
 def test_url_registration() -> None:
     """Check that URLs can be registered, then obtained."""
     plugin = AutorefsPlugin()
-    plugin.register_anchor(identifier="foo", page="foo1.html", primary=True)
+    plugin.register_anchor(identifier="foo", page=create_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", None)
@@ -28,7 +29,7 @@ def test_url_registration() -> None:
 def test_url_registration_with_from_url() -> None:
     """Check that URLs can be registered, then obtained, relative to a page."""
     plugin = AutorefsPlugin()
-    plugin.register_anchor(identifier="foo", page="foo1.html", primary=True)
+    plugin.register_anchor(identifier="foo", page=create_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", None)
@@ -41,7 +42,7 @@ def test_url_registration_with_from_url() -> None:
 def test_url_registration_with_fallback() -> None:
     """Check that URLs can be registered, then obtained through a fallback."""
     plugin = AutorefsPlugin()
-    plugin.register_anchor(identifier="foo", page="foo1.html", primary=True)
+    plugin.register_anchor(identifier="foo", page=create_page("foo1.html"), primary=True)
     plugin.register_url(identifier="bar", url="https://example.org/bar.html")
 
     # URL map will be updated with baz -> foo1.html#foo
@@ -60,7 +61,7 @@ def test_url_registration_with_fallback() -> None:
 def test_dont_make_relative_urls_relative_again() -> None:
     """Check that URLs are not made relative more than once."""
     plugin = AutorefsPlugin()
-    plugin.register_anchor(identifier="foo.bar.baz", page="foo/bar/baz.html", primary=True)
+    plugin.register_anchor(identifier="foo.bar.baz", page=create_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") == (
@@ -96,7 +97,7 @@ def test_find_closest_url(base: str, urls: list[str], expected: str) -> None:
 def test_register_secondary_url() -> None:
     """Test registering secondary URLs."""
     plugin = AutorefsPlugin()
-    plugin.register_anchor(identifier="foo", page="foo.html", primary=False)
+    plugin.register_anchor(identifier="foo", page=create_page("foo.html"), primary=False)
     assert plugin._secondary_url_map == {"foo": ["foo.html#foo"]}
 
 
@@ -105,8 +106,8 @@ def test_warn_multiple_urls(caplog: pytest.LogCaptureFixture, primary: bool) ->
     """Warn when multiple URLs are found for the same identifier."""
     plugin = AutorefsPlugin()
     plugin.config = AutorefsConfig()
-    plugin.register_anchor(identifier="foo", page="foo.html", primary=primary)
-    plugin.register_anchor(identifier="foo", page="bar.html", primary=primary)
+    plugin.register_anchor(identifier="foo", page=create_page("foo.html"), primary=primary)
+    plugin.register_anchor(identifier="foo", page=create_page("bar.html"), primary=primary)
     url_mapper = functools.partial(plugin.get_item_url, from_url="/hello")
     # YORE: Bump 2: Replace `, _legacy_refs=False` with `` within line.
     fix_refs('<autoref identifier="foo">Foo</autoref>', url_mapper, _legacy_refs=False)
@@ -120,8 +121,8 @@ def test_use_closest_url(caplog: pytest.LogCaptureFixture, primary: bool) -> Non
     plugin = AutorefsPlugin()
     plugin.config = AutorefsConfig()
     plugin.config.resolve_closest = True
-    plugin.register_anchor(identifier="foo", page="foo.html", primary=primary)
-    plugin.register_anchor(identifier="foo", page="bar.html", primary=primary)
+    plugin.register_anchor(identifier="foo", page=create_page("foo.html"), primary=primary)
+    plugin.register_anchor(identifier="foo", page=create_page("bar.html"), primary=primary)
     url_mapper = functools.partial(plugin.get_item_url, from_url="/hello")
     # YORE: Bump 2: Replace `, _legacy_refs=False` with `` within line.
     fix_refs('<autoref identifier="foo">Foo</autoref>', url_mapper, _legacy_refs=False)

tests/test_references.py

@@ -10,6 +10,7 @@
 
 from mkdocs_autorefs.plugin import AutorefsPlugin
 from mkdocs_autorefs.references import AutorefsExtension, AutorefsHookInterface, fix_refs, relative_url
+from tests.helpers import create_page
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -302,7 +303,7 @@ def test_register_markdown_anchors() -> None:
     """Check that Markdown anchors are registered when enabled."""
     plugin = AutorefsPlugin()
     md = markdown.Markdown(extensions=["attr_list", "toc", AutorefsExtension(plugin)])
-    plugin.current_page = "page"
+    plugin.current_page = create_page("page")
     md.convert(
         dedent(
             """
@@ -363,7 +364,7 @@ def test_register_markdown_anchors_with_admonition() -> None:
     """Check that Markdown anchors are registered inside a nested admonition element."""
     plugin = AutorefsPlugin()
     md = markdown.Markdown(extensions=["attr_list", "toc", "admonition", AutorefsExtension(plugin)])
-    plugin.current_page = "page"
+    plugin.current_page = create_page("page")
     md.convert(
         dedent(
             """
@@ -430,7 +431,7 @@ def test_mark_identifiers_as_exact(markdown_ref: str, exact_expected: bool) -> N
     """Mark code and explicit identifiers as exact (no `slug` attribute in autoref elements)."""
     plugin = AutorefsPlugin()
     md = markdown.Markdown(extensions=["attr_list", "toc", AutorefsExtension(plugin)])
-    plugin.current_page = "page"
+    plugin.current_page = create_page("page")
     output = md.convert(markdown_ref)
     if exact_expected:
         assert "slug=" not in output