feat: Add data-skip-inventory boolean attribute for elements to skip registration in local inventory

johnslavik · web-flow · commit f856160b03b2 · 2025-07-21T20:49:21.000+02:00
Issue-671: #671 PR-774: #774
diff --git a/src/mkdocstrings/_internal/extension.py b/src/mkdocstrings/_internal/extension.py
@@ -251,6 +251,15 @@ def _process_headings(self, handler: BaseHandler, element: Element) -> None:
 
         for heading in headings:
             rendered_id = heading.attrib["id"]
+
+            skip_inventory = "data-skip-inventory" in heading.attrib
+            if skip_inventory:
+                _logger.debug(
+                    "Skipping heading with id %r because data-skip-inventory is present",
+                    rendered_id,
+                )
+                continue
+
             # The title is registered to be used as tooltip by autorefs.
             self._autorefs.register_anchor(page, rendered_id, title=heading.text, primary=True)
 
diff --git a/src/mkdocstrings/_internal/handlers/base.py b/src/mkdocstrings/_internal/handlers/base.py
@@ -459,6 +459,7 @@ def do_heading(
         role: str | None = None,
         hidden: bool = False,
         toc_label: str | None = None,
+        skip_inventory: bool = False,
         **attributes: str,
     ) -> Markup:
         """Render an HTML heading and register it for the table of contents. For use inside templates.
@@ -469,6 +470,7 @@ def do_heading(
             role: An optional role for the object bound to this heading.
             hidden: If True, only register it for the table of contents, don't render anything.
             toc_label: The title to use in the table of contents ('data-toc-label' attribute).
+            skip_inventory: Flag element to not be registered in the inventory (by setting a `data-skip-inventory` attribute).
             **attributes: Any extra HTML attributes of the heading.
 
         Returns:
@@ -488,6 +490,8 @@ def do_heading(
         if toc_label is None:
             toc_label = content.unescape() if isinstance(content, Markup) else content
         el.set("data-toc-label", toc_label)
+        if skip_inventory:
+            el.set("data-skip-inventory", "true")
         if role:
             el.set("data-role", role)
         if content:
