feat: enable mixed markdown and HTML header IDs (#806)

* feat: enable mixed markdown and HTML header IDs

This enables markdown2's `mixed=True` setting of the header-ids extra.

* [autofix.ci] apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: mrossinek

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ## Unreleased: pdoc next
 
+- Include included HTML headers in the ToC by default by enabling markdown2's `mixed=True` option of the `header-ids` extra
+  (#806, @mrossinek)
 
 ## 2025-04-21: pdoc 15.0.3
 

pdoc/render_helpers.py

@@ -61,7 +61,7 @@
     "cuddled-lists": None,
     "fenced-code-blocks": {"cssclass": formatter.cssclass},
     "footnotes": None,
-    "header-ids": None,
+    "header-ids": {"mixed": True, "prefix": None, "reset-count": True},
     "link-patterns": None,
     "markdown-in-html": None,
     "mermaid": None,

test/test_render_helpers.py

@@ -110,6 +110,22 @@ def test_markdown_toc():
     assert to_html("#foo\n#bar").toc_html  # type: ignore
 
 
+def test_mixed_toc():
+    """
+    markdown2 can handle mixed markdown and HTML headings.
+
+    Let's test that this works as expected.
+    """
+    expected = [
+        "<ul>",
+        '  <li><a href="#foo">foo</a></li>',
+        '  <li><a href="#bar">bar</a></li>',
+        "</ul>",
+        "",
+    ]
+    assert to_html("#foo\n<h1>bar</h1>").toc_html == "\n".join(expected)
+
+
 @pytest.mark.parametrize(
     "md,html",
     [