Improve collapsible block styles; give special treatment for collapsible "results"

[eric-schneider]

We need to give some love to the collapsible block.

Current styling:

The current styling doesn't match the original spec.

Original spec:

Collapsible results

In the past we've used tabsets to show a command and its output/results in separate tabs (example):

However, this presents a problem since many of our code examples span multiple API clients. If someone can switch between Python, TypeScript, and Java, we would need to provide separate results for each client and this gets messy.

The current workaround is to switch to using a collapsible section underneath the corresponding code block. In fact, the original spec actually hinted at this workaround:

This was a late addition to the spec that didn't get much discussion and was never implemented in the new UI. The downside of a collapsible block is that it currently presents a small clickable target that isn't as easy to notice/use as tabs are.

We should consider enhancing the UI to treat command + results as a special case that warrants its own special UI treatment. If possible, we should consider implementing this on the AsciiDoc side in such a way that doesn't require (but still allows) using the full collapsible block syntax.

[colegoldsmith]

@eric-schneider I'm trying to find other examples of this in the wild to get some inspiration. So far I found the OpenAI Cookbook pages to have a somewhat similar design problem of showing a code block that is the "instructed input" with another code block as the ideal results. I feel like this is really specific to command line tools so I'm trying to find well designed docs sites on them. The issue I'm seeing is documentation for command line tools is typically --help... not some fancy schmancy website with code blocks 😆

[eric-schneider]

@djsauble @polandll if you happen to know of any other docs sites that do a good job of showing expected command output, feel free to post them here.

[polandll]

Really, in ANY command of any type, it is really helpful to users to see what they should expect. Not just for command line tools. It shorts the number of support messages/calls/whatever. I don't happen to have any results at my fingertips, frankly. I kind of like to think that this is a super-cool innovation that we did. 🤣

[eric-schneider]

I spoke with @KimberlyFields this morning, and she said that we should at least update the collapsible styles to align with the original spec.

However, we're not totally satisfied with the original design. We don't think they stand out enough and we're worried that users won't see them as something they can/should interact with.

Kim pointed out that Stripe docs use a button style for certain collapsible content. We need to consider that block titles are customizable by the writer and thus will have varying length (the button would have to scale well). However, a button style might work well for collapsible "Results".

[aimurphy]

Tagging on to this: It appears the collapsible block titles are a smaller font size than the default font size.
This makes them rather small and diminishes them. It also looks kind of silly because the text inside is the normal size.

The screenshots above seem to be the same font size everywhere, so I don't know if something got switched up at some point unintentionally.

@eric-schneider / @colegoldsmith Should I make a new issue about the font size?

Edit: Update that I noticed the tiny font only happens to collapsibles inside tabs.
It also seems like it turns bold when it's inside a tab.

Outside:

Inside:

[eric-schneider]

@aimurphy Thanks for adding updated screenshots. The CSS indeed got updated at some point.

Also, no need to create a new issue. This issue should be used to capture all feedback related to the visual styling of the collapsible block, including title. (Though, the CSS for the title may be shared across other block elements, which we should pay attention to as well.)

[eric-schneider]

Another example of how others are approaching this type of feature: https://www.mongodb.com/docs/atlas/tutorial/insert-data-into-your-cluster/#insert-and-view-data