feat: Support rendering backlinks through handlers

pawamoy · pawamoy · commit dd69005d56d6 · 2025-02-24T21:09:35.000+01:00
Handlers must add `backlinks` HTML elements to their templates: ```html <backlinks identifier="some-id" handler="handler-name" /> ``` mkdocstrings will run a regular expression substitution on each page's HTML, and call corresponding handlers' `render_backlinks` method with backlinks fetched from autorefs (using the specified identifier, and aliases obtained thanks to it through the same handler). Issue-723: #723 Issue-mkdocstrings-python-153: mkdocstrings/python#153 PR-739: #739
diff --git a/src/mkdocstrings/handlers/base.py b/src/mkdocstrings/handlers/base.py
@@ -21,7 +21,7 @@
 from markdown.extensions.toc import TocTreeprocessor
 from markupsafe import Markup
 from mkdocs.utils.cache import download_and_cache_url
-from mkdocs_autorefs import AutorefsInlineProcessor
+from mkdocs_autorefs import AutorefsInlineProcessor, BacklinksTreeProcessor
 
 from mkdocstrings._download import download_url_with_gz
 from mkdocstrings.handlers.rendering import (
@@ -44,7 +44,7 @@
     from collections.abc import Iterable, Iterator, Mapping, Sequence
 
     from markdown import Extension
-    from mkdocs_autorefs import AutorefsHookInterface
+    from mkdocs_autorefs import AutorefsHookInterface, Backlink
 
 log = get_logger(__name__)
 
@@ -323,6 +323,10 @@ def render(self, data: CollectorItem, options: HandlerOptions) -> str:
         """
         raise NotImplementedError
 
+    def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]]) -> str:  # noqa: ARG002
+        """Render backlinks."""
+        return ""
+
     def teardown(self) -> None:
         """Teardown the handler.
 
@@ -412,6 +416,8 @@ def do_convert_markdown(
         treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level  # type: ignore[attr-defined]
         treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"  # type: ignore[attr-defined]
         treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph  # type: ignore[attr-defined]
+        if BacklinksTreeProcessor.name in treeprocessors:
+            treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id  # type: ignore[attr-defined]
 
         if autoref_hook:
             self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook  # type: ignore[attr-defined]
@@ -422,6 +428,8 @@ def do_convert_markdown(
             treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0  # type: ignore[attr-defined]
             treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""  # type: ignore[attr-defined]
             treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False  # type: ignore[attr-defined]
+            if BacklinksTreeProcessor.name in treeprocessors:
+                treeprocessors[BacklinksTreeProcessor.name].initial_id = None  # type: ignore[attr-defined]
             self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None  # type: ignore[attr-defined]
             self.md.reset()
             _markdown_conversion_layer -= 1
diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py
@@ -15,8 +15,10 @@
 from __future__ import annotations
 
 import os
+import re
 import sys
 from collections.abc import Iterable, Mapping
+from re import Match
 from typing import TYPE_CHECKING, Any, Callable, TypeVar
 from warnings import catch_warnings, simplefilter
 
@@ -38,6 +40,7 @@
 if TYPE_CHECKING:
     from jinja2.environment import Environment
     from mkdocs.config.defaults import MkDocsConfig
+    from mkdocs.structure.files import Files
 
 
 log = get_logger(__name__)
@@ -234,13 +237,44 @@ def _on_env_write_inventory(self, env: Environment, config: MkDocsConfig, *args:
             inv_contents = self.handlers.inventory.format_sphinx()
             write_file(inv_contents, os.path.join(config.site_dir, "objects.inv"))
 
-    on_env = CombinedEvent(_on_env_load_inventories, _on_env_add_css, _on_env_write_inventory)
+    @event_priority(-100)  # Last, after autorefs has finished applying cross-refs and collecting backlinks.
+    def _on_env_apply_backlinks(self, env: Environment, /, *, config: MkDocsConfig, files: Files) -> Environment:  # noqa: ARG002
+        regex = re.compile(r"<backlinks\s+identifier=\"([^\"]+)\"\s+handler=\"([^\"]+)\"\s*/?>")
+
+        def repl(match: Match) -> str:
+            handler_name = match.group(2)
+            handler = self.handlers.get_handler(handler_name)
+
+            # The handler doesn't implement backlinks,
+            # return early to avoid computing them.
+            if handler.render_backlinks.__func__ is BaseHandler.render_backlinks:  # type: ignore[attr-defined]
+                return ""
+
+            identifier = match.group(1)
+            aliases = handler.get_aliases(identifier)
+            backlinks = self._autorefs.get_backlinks(identifier, *aliases, from_url=file.page.url)  # type: ignore[union-attr]
+
+            # No backlinks, avoid calling the handler's method.
+            if not backlinks:
+                return ""
+
+            return handler.render_backlinks(backlinks)
+
+        for file in files:
+            if file.page and file.page.content:
+                log.debug("Applying backlinks in page %s", file.page.file.src_path)
+                file.page.content = regex.sub(repl, file.page.content)
+
+        return env
+
+    on_env = CombinedEvent(_on_env_load_inventories, _on_env_add_css, _on_env_write_inventory, _on_env_apply_backlinks)
     """Extra actions that need to happen after all Markdown-to-HTML page rendering.
 
     Hook for the [`on_env` event](https://www.mkdocs.org/user-guide/plugins/#on_env).
 
     - Gather results from background inventory download tasks.
     - Write mkdocstrings' extra files (CSS, inventory) into the site directory.
+    - Apply backlinks to the HTML output of each page.
     """
 
     def on_post_build(
