Improve in-page ToC

[eric-schneider]

We should consider making some usability improvements to the in-page ToC (right-hand nav).

On width-constrained screens, we simply move the ToC to the top of the page. This means that if you land on a section in the middle of the page (either from xref or search) you won't even see the ToC, and using it requires you to scroll all the way back to the top. Also, since the ToC doesn't collapse, large ToCs take up a lot of real estate. We should consider better collapse behaviors that are more useful and take up less room.

We might also consider making visual improvements so that it's easier to identify which page section you're currently scrolling offer better support for third-level section headers.

[aimurphy]

Adding on that when the miniTOC is at the top of the page, it should break & collapse at a certain point. Here's an example from Puppet docs that shows this behavior:

[aimurphy]

Also, I am using a Dell U2719DX monitor, and I tend to keep my windows split 50/50 (chrome on one side, vscode on the other). I noticed that the miniTOC breaks to the top when the viewport is 1439px wide or less. My monitor is 2560px wide, so it's breaking to "tablet view" (for lack of a better term) before 50% width, which is what led me to believe that the miniTOC was permanently at the top of the page.

[aimurphy]

@eric-schneider I just noticed the color is different depending on the position.

Narrow viewport, where minitoc is between the title and the content

All H2 are purple and there is no hover color for H2. H3 are grey and change to purple on hover.

Wide viewport when the minitoc is to the right

All H2 are white and change to purple on hover. All H3 are grey and change to purple on hover.

Of course, the colors I'm describing are in dark mode. The same behavior happens in light mode.