Docs: Collapsible admonitions that start collapsed should be more accessible

[trgeiger]

For longer file examples or command outputs, we currently use several collapsible admonition blocks on our docs site. It's not immediately obvious that these are expandable without some textual indication.

To improve accessibility and the general UX of the docs, we should add some indication that these are expandable to the admonition titles, or perhaps consider having all collapsible blocks start expanded.

[m1kola]

I'm not an accessibility expert at all, but I checked with VoiceOver and it announces when you reach an expandable block and suggests how to expand or collapse it. I'm not sure if overall screen reader accessibility of the docs website is good enough. To improve accesibility we will likely have to contribute to mkdocs-material.

But I agree - even visually these blocks are not very intuitive. I do not have objections to either make them expanded by default or convert them non-collapsible admonitions.

[trgeiger]

Yeah I've been meaning to do a general once-over for general accessibility issues. I should probably make a main issue with subissues or something once I do that. This one example of the expandable admonitions just came up for me when I was doing some of the other docs stuff. Testing the screenreader is good, but I think this is also a more general UX issue since the admonitions aren't obviously expandable when they start closed.

[michaelryanpeter]

https://squidfunk.github.io/mkdocs-material/reference/admonitions/?h=expand#collapsible-blocks

All it would take is adding a + symbol to the ??? markup for the blocks you want expanded by default.

[github-actions]

Issues go stale after 90 days of inactivity. If there is no further activity, the issue will be closed in another 30 days.