Expand H2 to display H3 in floating TOC

[hillaryfraley]

Description

https://github.com/sensu/sensu-docs/pull/2544 includes a change to add a floating TOC that lists all of the H2 headings on each page.

We would like to add functionality to the floating TOC so that when a user clicks on one of the H2 headings, that H2 heading expands in the TOC to list the H3 headings it contains.

Category

This is an issue with:

• [ ] bug (bug in site build, layout, or functionality)
• [x] enhancement (add new or updated site functionality)

Affected pages

All

Expected behavior

The floating TOC lists all H2 headings on the page and when a user clicks one, it expands to list all the H3 headings it contains.

Current behavior

The floating TOC lists H2 headings on the page, but no H3 headings.

[hillaryfraley]

It's possible to adjust this code in config.toml so that endLevel = 3

  [markup.tableOfContents]
    endLevel = 2
    ordered = false
    startLevel = 2

This will display the H3 headings in the floating TOC. However, there are a couple formatting problems to solve:

• For some pages, including H3 headings makes the list of headings in the floating TOC too long to fit on the page. Scrolling with the mouse currently affects only the content part of the page -- you cannot scroll to the end of the floating TOC list without also scrolling to the bottom of the page. Need to decouple scrolling for the content and the floating TOC.
• H2 and H3 headings are improperly spaced in the floating TOC. Need to revisit line spacing in the floating TOC to better communicate heading hierarchy at a glance.

[hillaryfraley]

If possible, it would be helpful to make the H3 optional in the floating TOC. For some pages, the H3 headings will just clutter the TOC without much navigation improvement. For example, the H3s in the API docs are identical within H2s, and H2 alone is probably more helpful because it removes the H3 clutter from the floating TOC. Other pages, like the RBAC reference, seem like they are so long that a floating TOC with H3s could become too long itself.