Repository: mitmproxy/pdoc

Issue:
Include HTML headers in ToC
#### Problem Description

When a docstring includes HTML headers (`<h1>`, etc.) for example when I used an `.. include:: some_file.html` (or some markdown file which mixes markdown and HTML headers for some reason) directive, those headers are not included in the table of contents.

#### Proposal
markdown2 already supports this feature: https://github.com/trentm/python-markdown2/pull/538.
All one would need to do, is set `header-ids["mixed"] = True` for the header-ids extra, which pdoc already uses.


#### Additional Context
Essentially, I would consider this the reverse of the `markdown-in-html` setting, which is already supported by pdoc. So I do not see a reason not to support this.

Discussion:
@mhils: Sure, please send a PR!@mrossinek: > Sure, please send a PR!

Happy to do so! How should I approach this?
1. Should I simply enable mixed header-ids by default? E.g. through `"header-ids": {"mixed": True}` here: https://github.com/mitmproxy/pdoc/blob/ea2b69a4162226b07f68cd25d92d4d92dbbafaf8/pdoc/render_helpers.py#L64
2. Or should I add a new command-line argument, e.g. `--mixed-header-ids` which indicates this boolean value? One could leave its default to be `False`, therefore not changing the current behavior.@mhils: Definitely 1), we want to keep the CLI surface as small as possible.

Solution patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 747d22f..3337d33 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/pdoc/render_helpers.py b/pdoc/render_helpers.py
index 5c1f339..c96194b 100644
--- a/pdoc/render_helpers.py
+++ b/pdoc/render_helpers.py
@@ -61,7 +61,7 @@ markdown_extensions = {
     "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 patch:
diff --git a/test/test_render_helpers.py b/test/test_render_helpers.py
index c17740f..4279725 100644
--- a/test/test_render_helpers.py
+++ b/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",
     [