⚠️ GitHub is beta testing their own Admonition syntax. We should weigh in

Thanks for this informational table. I’m glad to see that it covers legacy systems such as Atlassian (Confluence) and newer ones like Obsidian.

Where did the Emoji Codes table come from?

That’s just my random collection of lookalikes.

2 Likes

But the overloading of the block-quote syntax > is still problematic. Ideally admonitions would be a wholly new syntax that doesn’t require re-purposing anything existing, as that would be chaos for tooling, not to mention a gross violation of POSH.

1 Like

I have seen a couple of different implementations of admonitions in Markdown.
These are:

  1. > Using blockquotes (MS & Github).
    Like @pboling said, I don’t think this is ideal, since an admonition is not a quote.
  2. ::: Using three colons to start and end a block (Docusaurus & Quarto).
    This defines a clear boundary of and admonition block.
  3. !!! Using three exclamation marks (MKDocs).
    This implies importance and doesn’t really work well for a note or a tip admonition.

My preference would be to go for option 2.

I think using emoji is a good idea for keeping it easy to read in all languages:

::: ℹ️
This is some info
:::
::: 💡
This is a tip
:::
::: ⚠️
This is a warning
:::
::: 🔥
This is danger
:::

So, basically, what @bb010g already proposed

1 Like

I don’t know what POSH stands for (web searched to no avail), but I don’t see why it is problematic. In fact, one of the best reasons for piggybacking on block-quote syntax is that results in gracefully degrading content – a reasonable rendering by older tools unaware of the new admonition syntax.

In fact, people have been doing this for years in READMEs and other files.

You can get pedantic about whether, in these gracefully degraded renderings, an admonition is a subclass of block quote. But from a purely visual perspective, it works great. At the end of the day, human readers of content can tell the difference. As to machines, it’s a matter of teaching them, and you have to do that whether you overload block quotes or use entirely different syntax.

My beef with GitHub’s approach is that they use English.

I think they mean “plain old semantic HTML” in which case it does pose an accessibility issue for some screen readers. It’s reasonable for a screen reader user to expect that when they hear “block quote [text] out of block quote” that [text] is a quote (be it another document, a book excerpt, something someone said), not something else. In the reverse, it would seem surprising that a block quote is quoting itself!

It does gracefully degrade for sighted users, but at the expense of the visually impaired, which I don’t think is an acceptable trade off. I’ve already encountered markdown-rendered documents in the wild that don’t properly transform “admonition block quotes” to regular divs.

The GitHub renderer doesn’t have this problem, but hiding admonitions away in block quotes and standardizing on it means that, for the next few years, a bunch of visually impaired users are going to be hearing confusing “block quote [text that isn't actually a quote] out of block quote” for things they were expecting to be block quotes.

‘nota’
’ poner la cuenta en su estado natural ’
‘’‘advertencia’‘’
‘’ necesito dinero no tengo nada ‘’

Another idea came up in the Github thread: authors could use multiple exclamation marks for increased importance. Also, it could be paired with an optional suffix, e.g.:

> [!]
> green/blue note level ℹ️

> [!! Caution]
> orange/yellow warning level ⚠️ 

> [!!! Danger !!!]
> red error level 🛑 

What about fully customizable admonitions?

  • Without title by default.
  • Emoji fully customizable (maybe :information_source: by default)
    • even with the option to put the url for an icon, using the embedded media syntax (![alt_text](url))
  • With the ability for them to be collapsable, like in Obsidian.
    • by default, not collapsible
    • + or - after the closing square bracket makes them collapsible, + making them open by default and - closed by default.

The format would then be: `[!<|emoji|img_url>]<|-|+> <|Admonition_title>

This could be part one of the specification, leaving background colors untouched. Part two could deal with deciding different background colors for each admonition type based on the emojis, a more time-consuming and possibly controversial task.

> [!]
> Generic markdown note. In the header of the note there's the default note emoji (maybe ℹ️), and there's not any title
> [!] My custom title
> Generic markdown note. In the header of the note there's the default note emoji (maybe ℹ️), and the title reads 'My custom title'
> [!💡]
> In the header of the note there's the 💡 emoji and there's no title.
> [!⚠️] Take care!
> In the header of the note there's the ⚠️ emoji and the title reads 'Take care!'.
> [!![♿](https://icons.getbootstrap.com/assets/icons/universal-access-circle.svg)] Accessibility
> In the header of the note there's a universal access circle icon (with fallback to the wheelchair emoji) and the title reads 'Accessibility'.
> [!🎵]- In-depth music theory explanation
In the header of the note there's the 🎵 emoji, the title reads 'In-depth music theory explanation', and the note is collapsible and collapsed by default.