Add a breakout/admonition/aside component

[delucis]

Currently we abuse the <blockquote> element to highlight bits of information, sometimes creatively combined with the Badge component. However these aren't usually actually quotes, so we shouldn't strictly speaking use <blockquote> to do this.

Many design systems include a component for this that usually supports different variations to highlight warnings, notes etc. Docusaurus calls them “admonitions” and the BBC's GEL system calls them “breakout boxes” for example. Docusaurus provides a Markdown shortcut to show these too, which we could mimic if we wanted.

Would something like this be useful? I built a component like this for another project based on the Astro docs template which could be a starting point: https://github.com/delucis/bgio-effects/blob/latest/docs/src/components/Aside.astro

[yanthomasdev]

I agree with having a dedicated component for this. Screen readers read <blockquote> as "quotation block", which doesn't sound clear since these text blocks are generally a complementary warning/tip.

Would something like this be useful? I built a component like this for another project based on the Astro docs template which could be a starting point: https://github.com/delucis/bgio-effects/blob/latest/docs/src/components/Aside.astro

Your solution is a great starting point! It gives a better description since it reads as "complementary (warning/tip/note)". I also like what Docusaurus does with remark-admonitions to implement this component as part of Markdown syntax.

[sarah11918]

I love this idea, especially if the screen reader text highlight's that it's a callout/warning/tip instead of just "block quote."

Do I close this with, "ON THIS, ON THE REG"?? ;)

[sarah11918]

Adding the label core so it shows up to get @natemoo-re 's input on this today.

[delucis]

This is on my to-do for this week (hopefully tomorrow!) Definitely curious to hear if Nate has opinions. And also what the hell these things are called. No-one seems to agree…

[delucis]

Here’s my plan of action:

1. Add an <Aside> component

   • Props (all optional):

   • type: 'note' | 'tip' | 'info' | 'caution' | 'danger'

     This would change an icon for the box and some highlight colours. Any other types we want here?

   • title: An string to title the box. Would default to a generic string like “Note” or “Tip” depending on type.

2. Add a Markdown plugin to allow use of this component without resorting to importing and writing <Aside>. Syntax would likely be something like:

   :::tip Interesting tip!
   
   This is a very interesting tip
   
   :::

   Do we want that? Or do you prefer importing and using the component?

   <Aside type="tip" title="Interesting tip!">
   
    This is a very interesting tip
   
   </Aside>

[sarah11918]

1. I'm thinking about the emoji we currently use in <blockquote> to get an idea of what we might want:
   • stack of books for "learn/read more" (but, these are only occasionally in blockquotes? Maybe we should check for consistency and make sure they are all pulled out. These will all be links, so we could keep them out of asides since they'll stand out anyway, being links. Or, we could have a "learn more (on another page)" kind of aside.)
   • lightbulb for tips/notes/notice me! --> these could be split out between info/tip
   • gear for setup/config info --> there are cases where we call attention to HEY, SET UP OR CONFIG LIKE THIS , but I don't think this occurs in a blockquote. Do we think this means some kind of "config/setup"-specific note might be useful?
   • warning sign for potential trouble (I'm not sure we distinguish between caution and full-out danger right now)

So in use right now is basically "hey!" and "whoa!" We could replace what we have with only two specific types. I like splitting up our lightbulb into "info" (kind of boring, procedural, works like this), and "tip" (maybe do this? for your consideration?). I'm not sure I would consistently be able to distinguish warning from danager, though? I might always be second-guessing myself about how serious something is!

I'll think about whether I can envision any other type that would be useful, but even just two to start would cover our existing docs.

2. I don't have a strong opinion regarding component vs plugin. I suppose the component might give us more flexibility? And maybe makes it easy to know exactly what is happening in the code, with signposts to trace down that component? And, asides are typically their own lines, so we shouldn't have to worry about inlining them and causing other problems within Markdown. But, I'm OK with either! Are there any trade-offs to consider?

[delucis]

• I like the idea of a “learn” type with the books.

• I also like “tip” (lightbulb) as a more playful extra thing

• Do we still need “info” and “note” then? Maybe just “tip” + “info” is enough otherwise we won’t be consistent in choosing?

• I think “danger” will be rare. Like when we need to say “Be careful! Running this command might wipe your hard drive” or something…

• I would keep the gear/config thing out of these boxes: the semantic idea is that everything these boxes is an aside — complementary content that you may not need. Anything that is “required reading” should go in the flow as bullet points our paragraphs.

  Here’s how the BBC’s guidelines describe it:

  Sometimes its worth noting or alerting users to certain information, but that information cannot be considered part of the main narrative for the document. This is what the Breakout box component is for.

  Breakout boxes can contain tips, warnings, research notes, interesting facts, and all sorts of tangential information.

For component vs plugin — I marginally prefer the plugin because I suspect it might render better on GitHub if that’s any kind of concern, but need to double check. Shouldn’t make any difference in terms of flexibility.