Mkdocs-material: Collapsable menu for sections

[digitalcraftsman]

Hi @squidfunk,

your theme supports nested menus, e.g. you have many section that contains multiple files that are linked.

This would create a very long menu. Would it be possible to integrate an option that allows users to collapse such sections?

[squidfunk]

Yes, we could do it via an option. As stated in the open discussion, I'm currently thinking about refactoring the theme a bit, so I will put it on my internal list.

[bladorf]

One thing to add - there are some themes running around (see http://helpmonks.github.io/docs/) that have already integrated collapsible menus, but it seems that in doing so they've done away with the nice navigation for header sections within files.

A hybrid of the two would be best - still allow a '##' header to show up in the side navigation, but also allow the collapsing element to deal with long documentation.

[d0ugal]

For what it's worth, helpmonks is just using a customised version of the readthedocs theme. It sort-of works, but isn't ideal.

[squidfunk]

Well, implementing collapsible sections is no rocket science, but the implementation in the read the docs theme from helpmonks is very bad - on mobile, when I open a section, the drawer closes. Therefore I have to open the drawer again to see what the section contains.

The refactored version of the Material theme will definitely have collapsible sections. Loading a page, the current path/section will be open by default and show the table of contents underneath it. However, on desktop the menu will most probably be on the left and the table of contents on the right, like in Google's documentation template which I like a lot.

Hopefully I will have some time in the near future for the next iteration of the Material theme.

[d0ugal]

... like in Google's documentation template ...

Got a link to that?

[squidfunk]

@d0ugal e.g. https://developers.google.com/protocol-buffers/docs/reference/overview

I think it's pretty functional and uses the space on desktop better than the Material theme. It won't be an exact copy, but somewhat inspired by this theme. However, the Google docs kind of suck on the iPhone and on smaller screens in general.

[squidfunk]

Another little preview: I borrowed the idea with the download and GitHub link at the bottom - I think it's a quite good call to action.

[d0ugal]

Thanks for the link, their docs do look nice. I'm also a fan of those links at the bottom, good call.

[squidfunk]

Thanks. I realized that a lot of people clicked the "STAR" button, but didnt't star the repository, because GitHub doesn't allow starring or forking it from external sources, so those actions are a two-step process. For this reason I renamed "STAR" to "STARS", but that didn't help improve on it much. For this reason I think it's better to show the stars next to the GitHub icon not in form of a button, but just as text, so it doesn't look like its possible starring it from external sources. It will just take the user to GitHub. That's at least what I learned from my logs.

[squidfunk]

Fixed in upcoming 1.0.0, see #46. Issue will remain open until release.

[nathanaa5]

@squidfunk How do I create collapsible navigation? I compiled a markdown file to HTML that contains an H1 header and many H2, H3, etc. The navigation shows up on the right side but it isn't collapsible. I've searched all over the repo but can't find documentation on how to make it collapsible. Please help, thank you!

[squidfunk]

The table of contents isn't collapsible, I'm sorry. You have to implement it yourself.

[nathanaa5]

So what is collapsible? I thought that's what this issue and the release notes talking about adding collapsible navigation was referring to.

How do I implement it myself for TOC?

[squidfunk]

Only the navigation is collapsible (on the left side), not the TOC.

[nikita-fuchs]

Could it be made a thing, please ? Makes manually created TOCs so much more tidy.

[squidfunk]

@nikita-fuchs you mean an auto-collapsing table of contents, so that only the active section is expanded? That's on the roadmap for Insiders.