feat: Add optional-hover ref type

This additionally adds the full identifier as hover text, which
is useful for certain references that could be generated by
mkdocstrings.

PR #10: #10

Author: bkoropoff

src/mkdocs_autorefs/references.py

@@ -11,7 +11,7 @@
 from markdown.util import INLINE_PLACEHOLDER_RE
 
 AUTO_REF_RE = re.compile(
-    r"<span data-(?P<kind>autorefs-identifier|autorefs-optional|mkdocstrings-identifier)="
+    r"<span data-(?P<kind>autorefs-identifier|autorefs-optional|autorefs-optional-hover)="
     r'("?)(?P<identifier>[^"<>]*)\2>(?P<title>.*?)</span>'
 )
 """A regular expression to match mkdocs-autorefs' special reference markers
@@ -150,17 +150,22 @@ def fix_ref(url_mapper: Callable[[str], str], unmapped: List[str]) -> Callable:
     def inner(match: Match):
         identifier = match["identifier"]
         title = match["title"]
+        kind = match["kind"]
 
         try:
             url = url_mapper(unescape(identifier))
         except KeyError:
-            if match["kind"] == "autorefs-optional":
+            if kind == "autorefs-optional":
                 return title
+            elif kind == "autorefs-optional-hover":
+                return f'<span title="{identifier}">{title}</span>'
             unmapped.append(identifier)
             if title == identifier:
                 return f"[{identifier}][]"
             return f"[{title}][{identifier}]"
 
+        if kind == "autorefs-optional-hover":
+            return f'<a title="{identifier}" href="{escape(url)}">{title}</a>'
         return f'<a href="{escape(url)}">{title}</a>'
 
     return inner

tests/test_references.py

@@ -185,3 +185,12 @@ def test_custom_optional_reference():
     output, unmapped = fix_refs(source, url_map.__getitem__)
     assert output == 'foo <a href="ok.html#ok">ok</a>'
     assert unmapped == []
+
+
+def test_custom_optional_hover_reference():
+    """Check that optional-hover HTML-based references are expanded and never reported missing."""
+    url_map = {"ok": "ok.html#ok"}
+    source = '<span data-autorefs-optional-hover="bar">foo</span> <span data-autorefs-optional-hover=ok>ok</span>'
+    output, unmapped = fix_refs(source, url_map.__getitem__)
+    assert output == '<span title="bar">foo</span> <a title="ok" href="ok.html#ok">ok</a>'
+    assert unmapped == []