Improve toggle button design and structure

[choldgraf]

Description / Summary

There are a few ways in which our current togglebutton UI/UX is sub-optimal:

• The buttons are off to the right, which makes them harder to see
• Because they're to the right, they behave weirdly on some screen sizes (see Buttons are cut off on narrow screens #26)
• The admonition toggles use a button to the right as well, which is also hard to see

This is an issue to track some improvements on these patterns. A few ideas that I think were originally proposed by @chrisjsewell in the EB Slack:

• the toggle class for standalone content should behave similarly to sphinx-design, where the element takes up some vertical space in the document flow, rather than being off to the side. This could use a <details><summary> combo and look something like:

  

• the toggle class for admonitions should convert the entire "title" area into a clickable field (e.g., with a label/input combination that spans the entire title area of the admonition), so that a user can click the whole admonition title to see a dropdown. See for example this dropdown from Quarto which does this nicely:

  

Other inspiration

JupyterLab:

ObservableHQ:

Value / benefit

Improving this would also improve how cell input / output hiding works in Jupyter Book, since we re-use this extension there.

Implementation details

sphinx-design is a good place to look for inspiration about what UI could look like - we should also look at other documenation engines that allow for "click to reveal" behavior, to see if there's some we quite like.

For the admonition-based toggle button, I think it should be relatively easy to achieve a label that spans the whole title field by injecting something like:

<label class="toggle-label" for="toggle-1-input"></label>
<input id="toggle-1-input" style="display; none;"></input>
```css
label.toggle-label {
	width: 100%;
    height: 100%;
    position: absolute;
    left: 0;
    top: 0;
    z-index: 999;
    cursor: pointer;
}

into the admonition p.admonition-title element

Tasks to complete

No response

[choldgraf]

cc @rkdarst who I believe is working on sphinx-lesson, which uses sphinx-togglebutton under the hood. Curious what you think about these proposals!

[rkdarst]

Thanks for notifying me! Indeed I do use it a lot (in sphinx_rtd_theme).

We don't usually use the toggle standalone, but the idea makes sense. The "entire admonition title is clickable" sounds like a great idea. I would be glad for either of these.

For your general info, we use this in several projects (also spread across many repositories). It is all sphinx_rtd_theme, for which sphinx-togglebutton (and sphinx-copybutton, and tabs) work perfectly - I guess that shows a good design? I would hope it would stay compatible out-of-the-box. I'm probably not good at the CSS/JS design but am happy to help however, to keep this working. You can see the sample rendering here: https://coderefinery.github.io/sphinx-lesson/sample-episode-rst/

The Quarto demo of a toggleable admonition looks like what I would want. I do wonder "will it be too easy to miss the symbol" (many people looking at our material are new and distracted with other stuff, so might miss it). But, overall, I guess this is minor: people will figure it out eventually and it's no big problem.