toc: add max_level option to limit which heading levels get anchor links

[rundef]

The TOC extension previously hardcoded anchor insertion for <h1>–<h6> via self.header_rgx = re.compile("[Hh][123456]"). This patch introduces a configurable max_level parameter, allowing users to restrict anchor links
(permalinks) to headings up to a specific level (default = 6).

Example:
TocExtension(anchorlink=True, max_level=2) adds anchors only to <h1> and <h2> elements.

[waylan]

Interesting. This is not a feature I would have ever considered. In fact, I am always frustrated when a site I am linking to does not give me more granular anchors to link to. I'm tempted to reject this for that pet-peeve alone, but recognize that there could be other factors. A stronger objection might be to avoid feature creep. So, can you make a case for why this should be included?

Assuming this does get accepted, another concern is the name of the option. "Max" seems illogical from a certain perspective. In fact, the proposed docs state "highest heading level (deepest <hN>)." 'Highest' and 'deepest' are opposites. I understand how we got here, but we need to account for document authors who don't understand HTML. And then there is the fact that the name does not connect it to anchorlinks specifically. I don't have any better names to propose, but want to make sure some thought was given to it at a minimum.

[rundef]

Thanks for the review, here's my use case:

<h2> are the major sections of my blog articles, I break section into small <h3> subjections, adding permalinks to these minor subsections is not desirable in my case

I suppose there must be other projects that use <hX>+ for layout/minor notes and might now want permalinks for those

I thought it would be a good idea to give more control to documentation/blog authors in general

[waylan]

<h2> are the major sections of my blog articles, I break section into small <h3> subjections, adding permalinks to these minor subsections is not desirable in my case

Why is it "not desirable?" This would annoy me. I want to link to the specific sentence I am referencing (or as close to it as possible). But if there are 3 h3 headings between the sentence and the linkable h2, that is annoying and I would expect those who are following the link to not find the sentence in question.

Regardless, for this to be approved it would need to pass all tests. For example, we don't use abbreviations in the prose in our documentation. When referring to the permalink setting by name, use a code span as the spell checker ignores code spans. However, in prose, they are referred to descriptively as "permanent links." In other words, only use words which are in the dictionary.

You would also need to add an entry to the changelog. See the Contributing Guide for details.

... See, isn't that helpful that I was able to link to the h4 specifically addressing the changelog? If all I had available was the h2, then you would have needed to scroll through quite a bit before getting there yourself. Even the h3 would have required significant scrolling. I just don't understand why anyone would want this option.

[rundef]

it's ok I'll just use my fork