feat: Add strip_title_tags option

The plugin records heading titles, and sets them as `title` attribute of cross-references (HTML links). Sometimes these titles contain HTML, and some MkDocs themes do not support HTML in them (they are shown as tooltips when hovering on links). This option allows to strip tags (while keeping text) from titles.

When set to `"auto"` (default value), it only strips tags for unsupported themes (all except Material for MkDocs).

Issue-33: #33

Author: pawamoy

Diff for: src/mkdocs_autorefs/plugin.py

@@ -76,6 +76,14 @@ class AutorefsConfig(Config):
     optionally appending the identifier for API objects.
     """
 
+    strip_title_tags: bool | Literal["auto"] = Choice((True, False, "auto"), default="auto")  # type: ignore[assignment]
+    """Whether to strip HTML tags from link titles.
+
+    Some themes support HTML in link titles, but others do not.
+
+    - `"auto"`: strip tags unless the Material for MkDocs theme is detected.
+    """
+
 
 class AutorefsPlugin(BasePlugin[AutorefsConfig]):
     """The `autorefs` plugin for `mkdocs`.
@@ -132,6 +140,7 @@ def __init__(self) -> None:
         self._get_fallback_anchor: Callable[[str], tuple[str, ...]] | None = None
 
         self._link_titles: bool | Literal["external"] = True
+        self._strip_title_tags: bool = False
 
     # YORE: Bump 2: Remove block.
     @property
@@ -313,6 +322,14 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         else:
             self._link_titles = self.config.link_titles
 
+        if self.config.strip_title_tags == "auto":
+            if getattr(config.theme, "name", None) == "material":
+                self._strip_title_tags = False
+            else:
+                self._strip_title_tags = True
+        else:
+            self._strip_title_tags = self.config.strip_title_tags
+
         return config
 
     def on_page_markdown(self, markdown: str, page: Page, **kwargs: Any) -> str:  # noqa: ARG002
@@ -399,6 +416,7 @@ def on_env(self, env: Environment, /, *, config: MkDocsConfig, files: Files) ->
                     file.page.content,
                     url_mapper,
                     link_titles=self._link_titles,
+                    strip_title_tags=self._strip_title_tags,
                     _legacy_refs=self.legacy_refs,
                 )
 

Diff for: src/mkdocs_autorefs/references.py

@@ -10,6 +10,7 @@
 from functools import lru_cache
 from html import escape, unescape
 from html.parser import HTMLParser
+from io import StringIO
 from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
 from urllib.parse import urlsplit
 from xml.etree.ElementTree import Element
@@ -376,22 +377,48 @@ def _find_url(
     raise KeyError(f"None of the identifiers {identifiers} were found")
 
 
-def _tooltip(identifier: str, title: str | None) -> str:
+def _tooltip(identifier: str, title: str | None, *, strip_tags: bool = False) -> str:
     if title:
         # Don't append identifier if it's already in the title.
         if identifier in title:
             return title
         # Append identifier (useful for API objects).
+        if strip_tags:
+            return f"{title} ({identifier})"
         return f"{title} (<code>{identifier}</code>)"
     # No title, just return the identifier.
+    if strip_tags:
+        return identifier
     return f"<code>{identifier}</code>"
 
 
+class _TagStripper(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.reset()
+        self.strict = False
+        self.convert_charrefs = True
+        self.text = StringIO()
+
+    def handle_data(self, data: str) -> None:
+        self.text.write(data)
+
+    def get_data(self) -> str:
+        return self.text.getvalue()
+
+
+def _strip_tags(html: str) -> str:
+    stripper = _TagStripper()
+    stripper.feed(html)
+    return stripper.get_data()
+
+
 def fix_ref(
     url_mapper: Callable[[str], tuple[str, str | None]],
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]],
     *,
     link_titles: bool | Literal["external"] = True,
+    strip_title_tags: bool = False,
 ) -> Callable:
     """Return a `repl` function for [`re.sub`](https://docs.python.org/3/library/re.html#re.sub).
 
@@ -406,6 +433,7 @@ def fix_ref(
             such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].
         unmapped: A list to store unmapped identifiers.
         link_titles: How to set HTML titles on links. Always (`True`), never (`False`), or external-only (`"external"`).
+        strip_title_tags: Whether to strip HTML tags from link titles.
 
     Returns:
         The actual function accepting a [`Match` object](https://docs.python.org/3/library/re.html#match-objects)
@@ -449,14 +477,14 @@ def inner(match: Match) -> str:
             if optional:
                 # The `optional` attribute is generally only added by mkdocstrings handlers,
                 # for API objects, meaning we can and should append the full identifier.
-                tooltip = _tooltip(identifier, original_title)
+                tooltip = _tooltip(identifier, original_title, strip_tags=strip_title_tags)
             else:
                 # Autorefs without `optional` are generally user-written ones,
                 # so we should only use the original title.
                 tooltip = original_title or ""
 
             if tooltip and tooltip not in f"<code>{title}</code>":
-                title_attr = f' title="{escape(tooltip)}"'
+                title_attr = f' title="{_strip_tags(tooltip) if strip_title_tags else escape(tooltip)}"'
 
         return f'<a class="{class_attr}"{title_attr} href="{escape(url)}"{remaining}>{title}</a>'
 
@@ -468,6 +496,7 @@ def fix_refs(
     url_mapper: Callable[[str], tuple[str, str | None]],
     *,
     link_titles: bool | Literal["external"] = True,
+    strip_title_tags: bool = False,
     # YORE: Bump 2: Remove line.
     _legacy_refs: bool = True,
 ) -> tuple[str, list[tuple[str, AutorefsHookInterface.Context | None]]]:
@@ -478,13 +507,14 @@ def fix_refs(
         url_mapper: A callable that gets an object's site URL by its identifier,
             such as [mkdocs_autorefs.plugin.AutorefsPlugin.get_item_url][].
         link_titles: How to set HTML titles on links. Always (`True`), never (`False`), or external-only (`"external"`).
+        strip_title_tags: Whether to strip HTML tags from link titles.
 
     Returns:
         The fixed HTML, and a list of unmapped identifiers (string and optional context).
     """
     unmapped: list[tuple[str, AutorefsHookInterface.Context | None]] = []
     html = AUTOREF_RE.sub(
-        fix_ref(url_mapper, unmapped, link_titles=link_titles),
+        fix_ref(url_mapper, unmapped, link_titles=link_titles, strip_title_tags=strip_title_tags),
         html,
     )
 

Diff for: tests/test_plugin.py

@@ -128,6 +128,7 @@ def test_use_closest_url(caplog: pytest.LogCaptureFixture, primary: bool) -> Non
     qualifier = "primary" if primary else "secondary"
     assert f"Multiple {qualifier} URLs found for 'foo': ['foo.html#foo', 'bar.html#foo']" not in caplog.text
 
+
 def test_on_config_hook() -> None:
     """Check that the `on_config` hook runs without issue."""
     plugin = AutorefsPlugin()
@@ -175,3 +176,39 @@ def test_explicit_link_titles(link_titles: bool | Literal["external"]) -> None:
     plugin.on_config(config=MkDocsConfig())
     assert plugin._link_titles is link_titles
 
+
+def test_auto_strip_title_tags_false() -> None:
+    """Check that `strip_title_tags` is made false when Material is detected."""
+    plugin = AutorefsPlugin()
+    plugin.config = AutorefsConfig()
+    plugin.config.strip_title_tags = "auto"
+    config = MkDocsConfig()
+    config.theme = Theme(name="material")
+    plugin.on_config(config=config)
+    assert plugin._strip_title_tags is False
+
+
+def test_auto_strip_title_tags_true() -> None:
+    """Check that `strip_title_tags` are made true when automatic and Material is not detected."""
+    plugin = AutorefsPlugin()
+    plugin.config = AutorefsConfig()
+    plugin.config.strip_title_tags = "auto"
+    config = MkDocsConfig()
+
+    config.theme = Theme("mkdocs")
+    plugin.on_config(config=config)
+    assert plugin._strip_title_tags is True
+
+    config.theme = Theme("readthedocs")
+    plugin.on_config(config=config)
+    assert plugin._strip_title_tags is True
+
+
+@pytest.mark.parametrize("strip_title_tags", [True, False])
+def test_explicit_strip_tags(strip_title_tags: bool) -> None:
+    """Check that explicit `_strip_title_tags` are kept unchanged."""
+    plugin = AutorefsPlugin()
+    plugin.config = AutorefsConfig()
+    plugin.config.strip_title_tags = strip_title_tags
+    plugin.on_config(config=MkDocsConfig())
+    assert plugin._strip_title_tags is strip_title_tags

Diff for: tests/test_references.py

@@ -53,6 +53,8 @@ def run_references_test(
     from_url: str = "page.html",
     extensions: Mapping[str, Mapping[str, Any]] | None = None,
     title_map: Mapping[str, str] | None = None,
+    *,
+    strip_tags: bool = True,
 ) -> None:
     """Help running tests about references.
 
@@ -71,7 +73,7 @@ def run_references_test(
     def url_mapper(identifier: str) -> tuple[str, str | None]:
         return relative_url(from_url, url_map[identifier]), title_map.get(identifier, None)
 
-    actual_output, actual_unmapped = fix_refs(content, url_mapper)
+    actual_output, actual_unmapped = fix_refs(content, url_mapper, strip_title_tags=strip_tags)
     assert actual_output == output
     assert actual_unmapped == (unmapped or [])