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.

Add test_external_link_with_anchor_preserved and testdata module to
verify README/included markdown links to external docs with anchors
remain intact.

Author: mbeijen

pdoc/render_helpers.py

@@ -306,6 +306,15 @@ def module_candidates(identifier: str, current_module: str) -> Iterable[str]:
         yield identifier
 
 
+# Pattern to find <a href="http(s)://...">...</a> for protection from linkify.
+# Identifiers in the href (e.g. #django.http.HttpResponseNotFound) must not be
+# rewritten as relative doc links (see issue with README links to external docs).
+_absolute_link_pattern = re.compile(
+    r'<a\s+href="https?://[^"]*"[^>]*>.*?</a>',
+    re.DOTALL,
+)
+
+
 @pass_context
 def linkify(
     context: Context, code: str, namespace: str = "", shorten: bool = True
@@ -319,6 +328,15 @@ 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).
     """
+    # Protect existing external links so identifiers in href (e.g. #django.http.HttpResponseNotFound)
+    # or in link text are not rewritten as relative documentation links.
+    placeholders: list[str] = []
+
+    def save_absolute_link(m: re.Match[str]) -> str:
+        placeholders.append(m.group(0))
+        return f"\u200b\u200bPDOC_EXT_LINK_{len(placeholders) - 1}\u200b\u200b"
+
+    code = _absolute_link_pattern.sub(save_absolute_link, code)
 
     def linkify_repl(m: re.Match):
         """
@@ -401,9 +419,8 @@ def linkify_repl(m: re.Match):
         # No matches found.
         return text
 
-    return Markup(
-        re.sub(
-            r"""
+    result = re.sub(
+        r"""
             # Part 1: foo.bar or foo.bar() (without backticks)
             (?<![/=?#&\.])  # heuristic: not part of a URL
             # First part of the identifier (e.g. "foo") - this is optional for relative references.
@@ -429,11 +446,13 @@ def linkify_repl(m: re.Match):
             (?:\(\))?
             (?=</code>(?!</a>))
             """,
-            linkify_repl,
-            code,
-            flags=re.VERBOSE,
-        )
+        linkify_repl,
+        code,
+        flags=re.VERBOSE,
     )
+    for i, original in enumerate(placeholders):
+        result = result.replace(f"\u200b\u200bPDOC_EXT_LINK_{i}\u200b\u200b", original)
+    return Markup(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,20 @@ 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