Easy integration, synergistic with existing syntax, to increase usability and adoption

[NerdyDeedsLLC]

Hey, sooooo....

box [?[DID YOU KNOW | There's currently no way to make one of these widely-recognized (from books and sites 
worldwide) call-out boxes on GitHub (short of using graphics, like I'm doing here). This is problematic, 
though, since not all GitHub markdown fields SUPPORT images.]]

box [*[SUGGESTIONS/IDEAS | I'd argue that something like these (which share great synergies with the rest of 
your syntax, but are easier to type out) would find even greater use and use-cases than diagrams, charts, & 
graphs.]]

box [i[INFORMATIVE NOTES | The box title could simply be the string before the pipe, the body after it, and 
the ability to \| escape one allow for its use therein ]]

box [i[Omitting the pipe entirely could simply cause the box to act as a space for text to be written, but 
far more attention-grabbing ]]

box [![Important MESSAGES | The character(s) between the square brackets could dictate the symbol 
loaded into the decor slot as well as dictating the color and style of the box.]]

box [!![VITAL NOTIFICATIONS|Simply increasing the number of bangs would be an easy way to 
select intensity...]]

box [!!![CRITICAL ALERTS|...perhaps capping out at 3?]]

---

Please don't misunderstand me here...

I'm absolutely in love with the Mermaid functionality. But it's hard to argue that there is a colossal amount of DOCUMENTATION currently being hosted on GitHub. As of June 2022, GitHub reported having over 83 million developers and more than 200 million repositories, including at least 28 million public repositories.

I think it would be reasonably safe to assert, therefore, we're looking at 220 MILLION README.md files alone. And that's notwithstanding the amount of comments, formal product documentation, wikis, issues, code review, helpfiles, gists, and discussions (like this one!). All that having been said, I would be utterly unsurprised to discover fully a billion pieces of text reference material that is in dire need of a mechanism to call out the critical parts.

flowchart LR
    id1{{ Now personally... I've long-since begun abusing them as a call-out mechanism already... }}
    style id1 fill:#fC6,stroke:#333,stroke-width:2px

Loading

...but it strikes me that instead of an obtuse, roundabout means of users invariably manipulating the syntax to accomplish this goal, might there not be...

%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
sequenceDiagram
A BETTER->WAY FORWARD: That might get utilized even MORE?
WAY FORWARD->A BETTER: (even in your OWN documentation?)
A BETTER->WAY FORWARD: Just sayin'....

Loading

[NerdyDeedsLLC]

(I figured I'd bring it up before attempting to work out a way to really abuse the functionality to generate something similar myself and bundling the result into a Chrome Extension for ease of implementation)

[ZenAtWork]

Wait, so, I assume the imagery/color/style and whatnot, are preset elements of the inserted template, and would just be automatically inserted when the box is generated by the Mermaid renderer? I suppose you could use a syntax similar to:

box [#BADA55|https://user-images.githubusercontent.com/123456789/123456789-.jpg[HEADER TEXT| Some message]]

...if you wanted to enable users to customize the color and icon, too!

[ZenAtWork]

Now THIS is a great idea. I would totally use this. I suspect my org would too. We use GH for MOST of our documentation. It'd be really nice to be able to make it more manual-esque!