Skip to content

Conversation

@rundef
Copy link

@rundef rundef commented Nov 9, 2025

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
Copy link
Member

waylan commented Nov 10, 2025

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.

@waylan waylan added the needs-decision A decision needs to be made regarding request. label Nov 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-decision A decision needs to be made regarding request.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants