Sub navigation broken if page doesn't start with title

[marcelstoer]

In order to avoid duplicate links in the (side) navigation it was suggested to remove the title of the page i.e. remove the header 1 or replace it with <h1> (#308 (comment)).

However, if you do this and omit the title MkDocs fails at rendering the (side) navigation correctly as it includes more than just header 1 & 2. If you start playing around with lower rank headers the behavior becomes totally incomprehensible.

In order to avoid any such confusion and undefined(?) behavior it might make sense to introduce a new configuration parameter that defines which max header level should be included in the navigation. That was what I initially thought was going on when I posted to your group https://groups.google.com/d/msg/mkdocs/JRufth2iBaE/L_W0ZsWlDAAJ.

[d0ugal]

The reason this happens is to do with how python-markdown creates the TOC tree which we then use. We include the top two levels in the table of contents, not h1 and h2.

So, this is really happening by design and as I would expect. It is confusing however, I think we should at some point consider a way of allowing users to customise this behaviour.

[marcelstoer]

I've just gone through #316 again and I agree that mkdocs.yml > md title > filename title would be a good strategy to find the TOC label (i.e. navigation item label).

Yet, I see perfectly valid use cases for TOC label != page titel. In such cases the page title shouldn't be part of the TOC. That's why I'd like to keep this open.

we should at some point consider a way of allowing users to customise this behaviour

What would help in those cases if you could define that markdown header N to header M should be part of the TOC (e.g. 2-3 but not 1 because that's the page title).

OR am I just missing something? How would you suggest we organize this http://nodemcu.readthedocs.org/en/dev/en/modules/hx711/? The firmware has dozens of modules and each should be listed in the TOC with its "shortname" while module page's title should/can be different.

[d0ugal]

You could just hide the first item in the table of contents with a tiny CSS addition. This would maintain the header tree for MkDocs to use and never show the first H1.

If you ever wanted to show an H1 in the table of contents it would be an issue tho'

See: #318 (comment)

[memeplex]

The css/js hack would be a real solution if the toc template always generated all header levels with an appropriately nested structure, letting the user manipulate it client-side. But in practice themes are opinionated (for good) regarding the way they render the toc, thus selectively hiding some level just leaves you with the wrong structure (for example, a one level hierarchy for a theme expecting two levels).