It's hard to believe this hasn't been suggested before (I assume it must have been), but my search-fu yielded only one 10-year-old post with little traffic, no accepted answer, and some very nostalgic screenshots.

A lot of Markdown flavors out there (including GitHub, Microsoft, MKDocs, and others) now support some variation of "Admonitions" or "Callouts". There is a still-active discussion on CommonMark which does a pretty good job documenting many of these extensions.

I write a lot of documentation, and my answers on StackOverflow tend to be very thorough. I use headings to try and break up the wall of text, but I often want to add a "NOTE", "CAUTION", or "WARNING" which will standout a bit from the background.

As it turns out, after some trivial searching, a lot of other authors also lean on callouts. At StackOverflow, folks have been rolling their own admonitions almost since the site got started.

• How to remove focus border (outline) around text/input boxes? (Chrome)
• Get the full URL in PHP
• How to fix Docker: Got permission denied issue
• Merge / convert multiple PDF files into one PDF
• How to round specific corners of a View?
• How to sort a file in-place?

The ubiquity of callouts/alerts/admonitions seems like a strong indicator that people want this feature.

Existing Solutions

Bold formatting

WARNING! I hope you don't miss this, otherwise your harddrive is toast.

This is a simple in-text callout which the author hopes will attract your attention before you copy-paste that bash command.

Additional formatting

If the warning is dire enough, we have additional formatting options to throw at the text:

⚠️ WARNING
Usually I include a callout when I'm about to share some code or advice that could really ruin your day if you don't take certain precautions.

Am emoji and some <hr> tags make the warning standout, but it's difficult to construct, conflicts with other (more legitimate) uses of <hr>, and looks pretty dang ugly.

Or, if want to make a "NOTE" less prominent, you can always abuse the <sub> tag (as seen in the most highly voted answer on Stack Overflow):

_{(Note some additional context which you can skip if you are in a hurry.)}

Code blocks

Some authors, particularly newer ones, attempt to add emphasis with code blocks. These usually get removed by editors, but it still points to users want to solve a problem.

WARNING: Using code blocks to add emphasis will attract the
attention of editors... and not in a good way.

Blockquotes

Blockquotes are great for what they were made for: quotations. But using them for callouts violates their semantic meaning and potentially causes confusion when you want to include both callouts and quotations.

⚠️ WARNING
This is not a quotation, but original prose meant to call out a common side-effect with potentially unwanted side-effects.

Not to mention their misuse in this regard has made some people mad (for good reason, as it messes with screen readers used by visually impaired users):

That paragraph […] is rendered in quote blocks. That means it's a quote. Where did you get the content from? You should cite your sources. If it's not a quote, it should not be in quote blocks. (If you want Markdown to be extended with more formatting options, request them on Meta.) Thanks.

Do we need a new Markdown formatting for indented / boxed text (for preambles, remarks / side notes, postscripts, footnotes, …)?
(emphasis mine)

Examples from other tools

Callouts are the prose version of syntax highlighting for <code> blocks: a reasonable extension of the CommonMark standard which would improve readability and semantic meaning.

I would love to have officially supported markdown and/or HTML for callouts, specifically "Note", "Caution", and "Warning", with an appropriate coloration and, ideally, a subtle icon for the sake of colorblind users.

GitHub

Since at least 2022, GitHub has offered the following markdown syntax:

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

With the following results:

MKDocs (with admonition extension)

With the admonition extension enabled, the following syntax:

!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Will render:

My Proposals

HTML Option: Add support for the role="note" attribute to <p>

I know that the SO staff have expressed concerns about deviating too much from the CommonMark standard.

But as an aside: your direct request of changing how these syntaxes work will never happen. We explicitly follow the CommonMark standard and will not deviate from it.

animuson (Staff) Commented May 31, 2022 at 17:28

This quote was very specifically about changing the way headers (#, ##, etc) are rendered. However, if that sentiment holds more generally, then I believe we could use a semantically correct and fully standards-compliant HTML solution which does not require any modification of the Markdown parser.

According to WAI-ARIA 1.3, role="note" seems to match exactly the purpose of a callout:

A section whose content represents additional information or parenthetical context to the primary content it supplements.

With this approach, we would have an aria-compliant solution with no possibility of conflicting with prior posts (since the role attribute has never been supported).

An icon (and color, if that's desirable) could be assigned (or not) based on the first word of the callout. A callout beginning with "Note", "NOTE", etc, could be assigned an information icon (ℹ️). Similarly for "Caution" (⚠️) and "Warning" (⛔️). Any other starting word would receive no icon, but would still be formatted appropriately.

Example:

<p role="note">
<strong>NOTE:</strong> Finally, a semantically appropriate element for a callout!
</p>

Markdown Option: Add new prefix syntax for blockquotes

According to the banner on https://talk.commonmark.org/:

Sticking to core CommonMark means there will be no new feature development. However, the CommonMark discussion site seems to encourage users to explore extensions and supersets. With that in mind, I believe that I've demonstrated a baseline justification for introducing an extension.

Users who want to add parenthetical content to their posts already frequently use (or "abuse") blockquotes. Adding a prefix line would reflect the pattern we already use for fenced code blocks, repeats a pattern seen on an extremely popular platform (GitHub), and wouldn't require a drastic departure from what users are already familiar with. It would also cause a minimal (perhaps even zero) amount of disruption to existing posts, while making it trivial to edit into many existing posts (where that is desirable).

For blockquotes, setting the first line to [!NOTE], [!CAUTION], or [!WARNING] would apply the appropriate formatting and title, including an icon and coloring. Or, to use the box formatting without the icon and title, use [!CALLOUT].

Example:

> [!WARNING]
> While this isn't exactly a quote, the formatting is different
> enough from other blockquotes that users can tell the difference.