ENH: add show_toc_level config option to choose visible levels of toc #256
Conversation
jorisvandenbossche
changed the title
| .. code-block:: python | ||
|
|
||
| html_theme_options = { | ||
| "show_toc_level": 2 |
There was a problem hiding this comment.
The "2" here might be a bit confusing with the above "only the 2nd-level headers ..." ?
There was a problem hiding this comment.
Yeah I wasn't quite sure what was the most intuitive thing to use here. The "2" could either refer to the level of the header in the document, OR it could refer to the level of the in-page TOC to the right. AKA the confusion is because the 2nd-level of the in-page TOC refers to the third level headers on the page. Do you have an intuition for which would be less-confusing for people?
There was a problem hiding this comment.
I think as config value, "2" is certainly fine here, in the meaning: "show 2 levels in the toc", which I think is the clearest definition (you don't need to know how to start counting the levels, include the main title as 1st level or not?)
There was a problem hiding this comment.
Actually, if there are multiple 1st level headers, it are actually those that are shown in the TOC. It's only the 2nd level headers that are shown if there is a single main title. So maybe it's better to speak about "only the 1st level headers (after the main title) of a page are shown"?
There was a problem hiding this comment.
I liked the language that you added, to make it clear that the configuration is for how many TOC levels are displayed (whether they begin with first-level headers or second-level headers, it'll remain consistent then)
Co-authored-by: Joris Van den Bossche <[email protected]>
This adds the ability to show deeper levels of the in-page TOC if users wish.
See the documentation demo for how this works.
closes #237