Customize level of headings that are wrapped in anchor links?

[adigitoleo]

Problem Description

Currently, pdoc renders markdown headings within docstrings (e.g. ### Heading) into HTML heading elements (e.g. h3). However, it is not possible to link to specific headings within a docstring because they are not wrapped in an <a>anchor</a> element.

My intended use case is to be able to reference specific headings in a module-level docstring (or in __init__.py), in the same way that I am able to reference class and function definitions in the API docs.

Proposal

Wrap rendered headings within docstrings in HTML anchor elements.

Alternatives

I guess the alternative is to manually maintain a TOC at the top of the docstring to at least give a quick visual overview.

[adigitoleo]

Oops, I think I'm being silly. There do seem to be anchor links in the published version of our docs, but not when I preview the live version on localhost. Is that intended? I'll check on another browser to be sure...

[adigitoleo]

OH ok, it only adds anchor links for h1 and h2. That seems sensible. Am I missing that in the pdoc docs somewhere? Or should it be added?

Feel free to close.

[mhils]

I don't think it's in the docs, but happy to merge a PR that adds it to the "header-ids" bullet in https://pdoc.dev/docs/pdoc.html#markdown-support! :)

[adigitoleo]

happy to merge a PR

Can do, I just want to clarify that markdown2 doesn't support customizing which heading level is the cutoff. That seems to be the case, am I right?

[mhils]

I don't know, this should be in the markdown2 docs. :)

…

On Fri, 9 Aug 2024, 16:17 Leon, ***@***.***> wrote: happy to merge a PR Can do, I just want to clarify that markdown2 doesn't support customizing which heading level is the cutoff. That seems to be the case, am I right? — Reply to this email directly, view it on GitHub <#725 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAHY2PTDVRFA4LLCQ6QYZLTZQTFQ3AVCNFSM6AAAAABMIOKDX2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDENZYGA2TIMJRGQ> . You are receiving this because you commented.Message ID: ***@***.***>

[adigitoleo]

Hmm, can't see anything. I think the part of markdown2 responsible for this is the "header ids" extra, which only has a brief wiki entry here. Nothing about h2 being the maximum. I tried searching in the 4k line markdown2 implementation for "header-ids" but couldn't work out where this limitation is coming from... In any case maybe the correct place to document this is in the header-ids wiki entry (that pdoc already links to) but I'd have to ask over there to find out what is going on.