feat: Allow external tools to insert references that are OK to skip

E.g. mkdocstrings-crystal can proactively insert links (by writing out the exact HTML that's prescribed here) that in the end can turn out to not be present anywhere, and since those are auto-inserted, they are not actionable for the user, so there should be no warning for them. So mkdocstrings-crystal will switch to `<span data-autorefs-optional="...">`.

Also migrate the "required" case to new data- keys, because this is not specific to mkdocstrings now.

PR #7: #7

Author: oprypin

src/mkdocs_autorefs/plugin.py

@@ -148,7 +148,7 @@ def on_post_page(self, output: str, page: Page, **kwargs) -> str:  # noqa: W0613
 
         Hook for the [`on_post_page` event](https://www.mkdocs.org/user-guide/plugins/#on_post_page).
         In this hook, we try to fix unresolved references of the form `[title][identifier]` or `[identifier][]`.
-        Doing that allows the user of `mkdocstrings` to cross-reference objects in their documentation strings.
+        Doing that allows the user of `autorefs` to cross-reference objects in their documentation strings.
         It uses the native Markdown syntax so it's easy to remember and use.
 
         We log a warning for each reference that we couldn't map to an URL, but try to be smart and ignore identifiers

src/mkdocs_autorefs/references.py

@@ -10,7 +10,10 @@
 from markdown.inlinepatterns import REFERENCE_RE, ReferenceInlineProcessor
 from markdown.util import INLINE_PLACEHOLDER_RE
 
-AUTO_REF_RE = re.compile(r'<span data-mkdocstrings-identifier=("?)(?P<identifier>[^"<>]*)\1>(?P<title>.*?)</span>')
+AUTO_REF_RE = re.compile(
+    r"<span data-(?P<kind>autorefs-identifier|autorefs-optional|mkdocstrings-identifier)="
+    r'("?)(?P<identifier>[^"<>]*)\2>(?P<title>.*?)</span>'
+)
 """A regular expression to match mkdocs-autorefs' special reference markers
 in the [`on_post_page` hook][mkdocs_autorefs.plugin.AutorefsPlugin.on_post_page].
 """
@@ -94,7 +97,7 @@ def makeTag(self, identifier: str, text: str) -> Element:  # noqa: N802,W0221 (p
             A new element.
         """
         el = Element("span")
-        el.set("data-mkdocstrings-identifier", identifier)
+        el.set("data-autorefs-identifier", identifier)
         el.text = text
         return el
 
@@ -152,6 +155,8 @@ def inner(match: Match):
         try:
             url = relative_url(from_url, url_mapper(unescape(identifier)))
         except KeyError:
+            if match["kind"] == "autorefs-optional":
+                return title
             unmapped.append(identifier)
             if title == identifier:
                 return f"[{identifier}][]"

tests/test_references.py

@@ -154,3 +154,21 @@ def test_ignore_reference_with_special_char():
         source="This [*a b*][].",
         output="<p>This [<em>a b</em>][].</p>",
     )
+
+
+def test_custom_required_reference():
+    """Check that external HTML-based references are expanded or reported missing."""
+    url_map = {"ok": "ok.html#ok"}
+    source = "<span data-autorefs-identifier=bar>foo</span> <span data-autorefs-identifier=ok>ok</span>"
+    output, unmapped = fix_refs(source, "page.html", url_map.__getitem__)
+    assert output == '[foo][bar] <a href="ok.html#ok">ok</a>'
+    assert unmapped == ["bar"]
+
+
+def test_custom_optional_reference():
+    """Check that optional HTML-based references are expanded and never reported missing."""
+    url_map = {"ok": "ok.html#ok"}
+    source = '<span data-autorefs-optional="bar">foo</span> <span data-autorefs-optional=ok>ok</span>'
+    output, unmapped = fix_refs(source, "page.html", url_map.__getitem__)
+    assert output == 'foo <a href="ok.html#ok">ok</a>'
+    assert unmapped == []