Allow for auto-collapsing sidenav a la Bootstrap's doc site

[SinisterMinister]

While working on a very large document, the sidenav ToC can be quite unwieldy where it will flow past the viewport with no way to scroll to access the remaining links, for instance:

Might be hard to see, but at the bottom, the edge of the browser window shows that there is more content beneath.

A solution to this would be to collapse the items when they're not active, much like how the right-nav items on the bootstrap docs do. Here's what it would look like in that case:

I've already written most of the code to do this and I think I can come up with a way to "enable" it via CSS. I'm more curious if this is a desired feature or not. I'd love to see it there as I plan to use this for this internal project's documentation, but those docs are quite lengthy, so I'm running into this problem often.

Let me know if you want this and I'll make a PR.

[chrissimpkins]

I was a bit concerned about this when we added the third level of headers to the sidebar in #9. I would definitely be in favor of this approach. Let's bring @trehn into the conversation for input since he added the third level headers in that pull request.

@SinisterMinister what change is involved and do you still feel that it would be possible to make this either default but optional, or non-default and activated as an option?

[chrissimpkins]

@SinisterMinister those docs look very nice btw :)

[trehn]

This seems like a reasonable way to help with long pages. I would prefer for it to be configurable per-page and off by default though, as most of my navs will fit easily on most screens and it would be a bit silly to collapse just two or three subheadings on short pages.

[SinisterMinister]

@chrissimpkins:

@SinisterMinister what change is involved

I had to refactor the ToC template a bit to achieve this. Made it match what they were doing on the Bootstrap docs.

and do you still feel that it would be possible to make this either default but optional, or non-default and activated as an option?

I think so. I had to dive a bit deeper into mkdocs to see what they were doing, but I think we can make this opt-in or opt-out, just need to know what your preference is.

I was a bit concerned about this when we added the third level of headers to the sidebar in #9

So, I added another level for my stuff, but I think I can make that configurable as well. Might hinge on what Jinja lets me do in the template.

@trehn:

I would prefer for it to be configurable per-page... as most of my navs will fit easily on most screens and it would be a bit silly to collapse just two or three subheadings on short pages.

I think this is doable as well using meta for a per page setting, and extra for global settings. Let me play around with this a bit and see.

[SinisterMinister]

Alright, I was able to get that setup. Here's how it would work:

Collapsable ToC

So right now, it defaults to disabled as that's the current implementation. To enable it, you can do so globally by setting extra.collapse_toc to true in your mkdocs.yml like so:

site_name: Nibiru Documentation
pages:
  - Home: index.md
  - Guides:
    - OpenStack Support: guides/openstack-support.md
theme: cinder
extra:
  collapse_toc: true

This will enable it site-wide. You can also use page-specific overrides by adding collapse_toc to the meta section of your page's markdown like so:

collapse_toc: true

# OpenStack Support
<small>Author: Codey Whitt</small>

## Differences Between AWS and OpenStack

There are only a handful of differences that could potentially cause you headaches while working with OpenStack instances and they are mostly edge cases. We'll start with the only one that isn't.

This way you can enable/disable it site-wide as well as override it on a page by page basis. You can have it enabled site-wide and disabled on individual pages or have it disabled site-wide and enabled individually as well.

Tunable ToC levels

The other thing I added since I needed more levels in my ToC was the ability to tune the number of levels shown in the ToC. I used the same pattern as before with the ToC collapsing as well. Here it is via mkdocs.yml:

site_name: Nibiru Documentation
pages:
  - Home: index.md
  - Guides:
    - OpenStack Support: guides/openstack-support.md
theme: cinder
extra:
  toc_levels: 4

And here it is on a page level:

toc_levels: 2

# OpenStack Support
<small>Author: Codey Whitt</small>

## Differences Between AWS and OpenStack

There are only a handful of differences that could potentially cause you headaches while working with OpenStack instances and they are mostly edge cases. We'll start with the only one that isn't.

The theme should default to 3 levels if not specified as it does currently. Also, if I need to pull this into a separate issue/PR, I can do that.

Thoughts?

[chrissimpkins]

I really like it Cody. Definitely favor more options that improve usability. I might need some assistance with the description of the new settings on the project documentation but we can address it once we merge. No separate issue report is needed. If you are willing to add all of the above suggestions that you made into a single PR (or multiple if you feel that we may need to work on them individually for any reason), I will definitely try to merge this over the weekend. These are all great changes. Thanks!

[SinisterMinister]

Alright, I've got the #15 PR done with all the updated docs and then some. You might want to decline #13 as this includes the same fix, or just merge them in order. ¯\_(ツ)_/¯

[SinisterMinister]

Oh, I didn't build the actual site though, so you'll still need to do that. Just FYI.

[SinisterMinister]

I should also add that I changed toc_levels to toc_depth as it felt a bit more correct. I can change it back if you'd like. Just let me know.

[davidban77]

Any chance this functionality could be added? :) @SinisterMinister @chrissimpkins

Really looking forward to it... I have some reference docs that could greatly benefit from this :)