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

Extensions
21

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

22

Where did the Emoji Codes table come from?

23

That’s just my random collection of lookalikes.

2 Likes
24

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
25

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
26

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.