Showing only #/h1 anchors as children in the table of contents?

[joshdholtz]

Hello!

I’m the lead maintainer of https://github.com/fastlane/fastlane and I’m working on upgrading our docs 😊 We are currently on a super old version of mkdocs and I’m upgrading to 1.1.2

We were using pymdown-extensions with pymdownx.headeranchor (I think) to have anchors show as children

Example of current website

It seems like this took all # and used those as children

Current status of upgrade to 1.1.2

pymdown-extensions no longer has pymdownx.headeranchor so I think this is my part of my issue.

Now it seems like my children as all ## under the first # 🤷‍♂️

So my question...

Is there a way to adjust how markdown/toc determines what children returns? 😁

[Andre601]

I can't find headeranchor in PyMdown's docs so it perhaps is no longer supported?
The closest thing I found is saneheaders, but I assume it doesn't do what you need.

You should consider using the Table of Contents extension of the python markdown lib.
I'm not sure what your goal here is tbh (Since I lack the general knowledge to begin with) but if your goal is to only display headers up to a specific level can you use the baseLevel of the ToC extension to set the highest (or lowest?) level a header can have to be displayed.
Perhaps the toc_depth is also an option?

[joshdholtz]

OMG, that was the quickest response of all time! Thank you 😊

Yeah yeah, that headeranchor is no longer supported (we were on a REALLLLLLYYY old version). I will look into both baseLevel and toc_depth. Thank you!

I live in the Ruby world and spend a lot of time in Jekyll so I’m really out of my league here 😛

[waylan]

You can use the toc_depth option of the TOC extension for this. Setting it to 3 would give you the top three levels. Setting it to 6 would give you all six levels. MkDocs already uses the toc extension by default. However, you can override the defaults and provide your own options to it.

That said, some themes hard-code the number of levels they support. In that case, you can only use the toc_depth setting to reduce the number of levels, not to increase it.

However, some themes may provide a theme specific setting which controls this. For example, both the mkdocs and readthedocs themes provide a navigation_depth setting (defaults to 2 for mkdocs and 4 for readthedocs). Check the documentation for the theme you are using. If such a setting is supported, you will likely want to use that rather than the toc_depth setting of the Markdown extension.

[joshdholtz]

I think I found my problem 😱 It looks like the TOC extension doesn’t see all # as a children. It will only get things under the first #. I need to rework my pages to only have one top level # 🤷‍♂️

I tried adjusting the toc_dept but I can’t get it to show all the # as children but it’s easy enough to just add an extra # onto each heading in each file 😇

Thanks to @Andre601 and @waylan for pointing me in the right direction! ❤️

[Andre601]

From what I once gathered is this a intentional behaviour...?

Like looking at squidfunk/mkdocs-material#818 (comment) does it seem like that only a single h1 header is supported for a Page when using HTML5, which I assume MkDocs and most of its themes do use.

So what you encountered was mostly a normal behaviour caused by how html5 treats h1 headers in article-like pages or something...