Limit the TOC level depth in extensions/toc

[the9000]

Use case

Take a document, such as an API description, or a document converted from Org mode, with lots of deep-level headers and very short texts under each of them.
A TOC of such a document becomes excessively long and detailed. (My particular case is what mkdocs generates.)

A fix

• Add a config parameter that optionally limits the maximum level of headers included in the TOC.
• Filter the levels where they are generated according to that parameter.

I'll gladly make a PR, but would appreciate any advice on the best way to add a config parameter.

[waylan]

I'm sure this is a duplicate, but I can't seem to find it, In any event, we have traditionally been resistant to adding more config options. That certainly has been the stated reason for not yet adding this feature in previous discussions (which I can't find now).

Regardless, the TOC level depth is completely controlled by themes from within the templates. Our position in the past has been that you should be able to override this with theme customization. However, it occurs to me that as themes can now define their own settings (as of version 0.17), this could be user configurable as a theme setting. I would be willing to consider a PR which added a theme setting to both of the built-in themes.

[mitya57]

@waylan Did you realize that this issue is for Python-Markdown, not for mkdocs?

I know that you are a developer of both projects, so this can be quite confusing :)

[waylan]

Oh whoops. Thanks for the headsup @mitya57.

[waylan]

Interestingly, the OP made this statement:

(My particular case is what mkdocs generates.)

So, in the end, I did point to the correct way to address this in MkDocs. Although, by default, the builtin MkDocs themes limit the depth to 2 so I'm not sure why you're having a problem with excessively deep TOC. If you are using a third-party theme, then take that up with the devs of that theme. Otherwise, you are free to submit a PR to MkDocs as stated above.

I'm not so sure I want to add that option to the Markdown extension.

It's quite common to use markdown headings for structure and viewability, including deeper level headings however in the TOC you may not want to call them all out. I have a document that has H1-H6, but I only want to show the higher level headings in the TOC, h1-h4.

[RoyiAvital]

@bpaduch ,

I would go even farther.
I would like to set the range of headers (Namely also the minimum).
As H1 is usually dedicated to the document title there is no sense of having it in the Table of Content.
So I'd like option to choose H2-H5 for instance.

[waylan]

@RoyiAvital that can be set with the extension options. Set baselevel=2. Or in a MkDocs config file do:

markdown_extensions:
    - toc:
        baselevel: 2

@waylan - I found the baselevel option doesn't actually limit headings but adjusts the headings, and essentially bumps them up so there is heading for that baselevel (just like in their example, a heading 1 and 2 becomes heading 3 and 4).

The same happens if I apply to my docs. For example, in markdown I have:

## Heading 2
### Heading 3
#### Heading 4
##### Heading 5

What comes out is that the parser reformats the heading level and bumps them up a level, so that the desired baselevel isn't rendered.

<h3>Heading 2 -> becomes heading 3
<h4> Heading 3  -> becomes heading 4
<h5>Heading 4 -> becomes heading 5
<h6> Heading 5 -> becomes heading 6

TBH, this is strange because now you have different heading levels from the actual markdown, and the contents for heading 2 still display, but now as an h3.

Maybe I'm interpreting incorrectly but that's the results that occur when I apply it.

[waylan]

@bpaduch my last comment was responding to @RoyiAvital's request which is different that yours. As I explained in previous comments, what you are requesting is not currently supported and I'm not inclined to add such a feature to the extension myself.

[RoyiAvital]

@waylan ,
I asked to be able to set a range of Headers (Say H2-H5) which will be shown in the Table of Content.
I don't understand how what you wrote does it.

[waylan]

@RoyiAvital you are asking for something different that the matter being discussed in this issue. If the comment I made doesn't address your issue, then please continue the discussion elsewhere.

[RoyiAvital]

The issue asks to have limit on the order of the header to be included in the generated Table of Content.
You can think as limiting it on one side.

All I asked is if someone puts effort in that he should have the option to limit form both sides.
Namely only put in the Table of Content headers with number minHeader to maxHeader.
For instance if minHeaderLevel = 2 and maxHeaderLevel = 4 then:

# Header Level 1 % Will be ignored
## Header Level 2 % Will be shown
### Header Level 3 % Will be shown
#### Header Level 4 % Will be shown
#### Another Header Level 4 % Will be shown
##### Header Level 5 % Will be ignored

[waylan]

Sorry @RoyiAvital I misunderstood your request. To me this whole request is not something I would ever want so when I saw your request I assumed you meant you wanted the baselevel feature.