Fix external links with anchors being rewritten as relative doc links

Protect <a href="https?://..."> links from linkify so identifiers in the
URL fragment (e.g. #django.http.HttpResponseNotFound) or in the link text
are not turned into relative documentation links. Mask such links with
placeholders before linkify, then restore them after.

Author: mbeijen

pdoc/render_helpers.py

@@ -306,6 +306,31 @@ def module_candidates(identifier: str, current_module: str) -> Iterable[str]:
         yield identifier
 
 
+@contextmanager
+def shield_fragments(code: str, pattern: str | re.Pattern[str], flags: int = 0):
+    """
+    Context manager that shields regex matches in `code` from being modified,
+    then restores them afterward.
+
+    Yields a tuple ``(shielded_code, restore)`` where ``shielded_code`` is the
+    input with all matches replaced by unique placeholders, and ``restore`` is a
+    callable that replaces the placeholders back with the original matches.
+    """
+    placeholders: list[str] = []
+
+    def save(m: re.Match[str]) -> str:
+        placeholders.append(m.group(0))
+        return f"\u200b\u200bPDOC_FRAGMENT_{len(placeholders) - 1}\u200b\u200b"
+
+    def restore(text: str) -> str:
+        for i, original in enumerate(placeholders):
+            text = text.replace(f"\u200b\u200bPDOC_FRAGMENT_{i}\u200b\u200b", original)
+        return text
+
+    shielded = re.sub(pattern, save, code, flags=flags)
+    yield shielded, restore
+
+
 @pass_context
 def linkify(
     context: Context, code: str, namespace: str = "", shorten: bool = True
@@ -319,7 +344,6 @@ def linkify(
     For example, replace "current_module.Foo" with "Foo". This is useful for annotations
     (which are verbose), but undesired for docstrings (where we want to preserve intent).
     """
-
     def linkify_repl(m: re.Match):
         """
         Resolve `text` to the most suitable documentation object.
@@ -401,8 +425,10 @@ def linkify_repl(m: re.Match):
         # No matches found.
         return text
 
-    return Markup(
-        re.sub(
+    with shield_fragments(
+        code, r'<a\s+href="https?://[^"]*"[^>]*>.*?</a>', re.DOTALL
+    ) as (code, restore):
+        result = re.sub(
             r"""
             # Part 1: foo.bar or foo.bar() (without backticks)
             (?<![/=?#&\.])  # heuristic: not part of a URL
@@ -433,7 +459,7 @@ def linkify_repl(m: re.Match):
             code,
             flags=re.VERBOSE,
         )
-    )
+    return Markup(restore(result))
 
 
 @pass_context

test/test_render_helpers.py

@@ -5,6 +5,7 @@
 import pytest
 
 from pdoc.render_helpers import edit_url
+from pdoc.render_helpers import linkify
 from pdoc.render_helpers import module_candidates
 from pdoc.render_helpers import possible_sources
 from pdoc.render_helpers import qualname_candidates
@@ -161,3 +162,25 @@ def test_mixed_toc():
 )
 def test_markdown_autolink(md, html):
     assert to_html(md) == html
+
+
+def test_external_link_with_anchor_preserved():
+    """
+    External links with anchors must not be rewritten as relative documentation links.
+    """
+    md = "See [HttpResponseNotFound](https://docs.djangoproject.com/en/6.0/ref/request-response/#django.http.HttpResponseNotFound)."
+    html = to_html(md)
+
+    # Minimal context so linkify runs (no modules to link to); tests that external links are preserved.
+    class FakeModule:
+        modulename = "test"
+
+        def get(self, name):
+            return None
+
+    ctx = {"module": FakeModule(), "all_modules": {}, "is_public": lambda doc: ""}
+    result = str(linkify(ctx, html))
+    assert (
+        "https://docs.djangoproject.com/en/6.0/ref/request-response/#django.http.HttpResponseNotFound"
+        in result
+    )