Include HTML headers in ToC

[mrossinek]

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: trentm/python-markdown2#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.

[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:

   pdoc/pdoc/render_helpers.py

   Line 64 in ea2b69a

   "header-ids": None,

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.