TOC: Include permalink for headers out of toc_depth range

[jayqi]

I would like to be able to enable permalinks for headers out of the toc_depth range. Currently only headers within the range get permalinks when permalink is enabled. (Markdown==3.3.3)

My use case is that I have pages that have a lot of headers. In order for the TOC to be not too large, I use toc_depth to only include higher levels in my TOC. However, I would like users to still be able to directly link to the out-of-range headers if they need to.

More concretely, I have API documentation for modules. My TOC only goes down to class names, as including method names would be too much, but I'd still like users to be able to link directly to method headers.

[waylan]

Well that's not how I thought things worked. I was about to say we already do what you are requesting, but checked first.

>>> import markdown
>>> from markdown.extensions.toc import TocExtension
>>> src = '''
... # Level 1
...
... ## Level 2
...
... ### Level 3
...
... #### Level 4
...
... ##### Level 5
...
... ###### Level 6
... '''
>>> md = markdown.Markdown(extensions=[TocExtension(permalink=True, toc_depth='2-4')])
>>> print(md.convert(src))
<h1>Level 1</h1>
<h2 id="level-2">Level 2<a class="headerlink" href="#level-2" title="Permanent link">&para;</a></h2>
<h3 id="level-3">Level 3<a class="headerlink" href="#level-3" title="Permanent link">&para;</a></h3>
<h4 id="level-4">Level 4<a class="headerlink" href="#level-4" title="Permanent link">&para;</a></h4>
<h5>Level 5</h5>
<h6>Level 6</h6>
>>> md.toc_tokens
[{'level': 2, 'id': 'level-2', 'name': 'Level 2', 'children': [{'level': 3, 'id': 'level-3', 'name': 'Level 3', 'children': [{'level': 4, 'id': 'level-4', 'name': 'Level 4', 'children': []}]}]}]

I don't think I ever intended to have that behavior. I would expect IDs and permalinks to be applied to all levels regardless of which levels are included in the TOC. And yet, that is clearly not the behavior we have now and the existing behavior is included in a few tests. I think we should make this change. I would consider the existing behavior a regression.

[jayqi]

Funny enough, this is explicitly documented in the docs for Material for MkDocs. Not sure if @squidfunk has a stance on this behavior if the default changes.

Note that MkDocs will not generate anchor links for levels outside the range defined with toc_depth.

https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#table-of-contents

[waylan]

We don't explicitly document this behavior. I checked the old PRs and issues addressing the code involved and I didn't find any discussion of the behavior for or against. I don't recall as it has been six years, but I'm assuming that I missed the change when I merged the PR provided by a third-party contributor.

[waylan]

The reported behavior has been changed in #1108 and a new release has been made (3.3.4). Also, I filed a bug report at
squidfunk/mkdocs-material#2342 suggesting that their documentation be updated.