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




I guess implementations could make it multilingual, so the words Note, Warning etc. could be in any language?

Emojis or abstract symbols like (!) are a better approach to i18n.


It’s worth going back to the core philosophy of Markdown and seeing how well this syntax fits in:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

GitHub’s proposed syntax fits this part quite well.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean.

The use of strong emphasis may be suitable here, but perhaps the words “Warning” and “Info” should be considered heading text instead? Alternative proposal:

> # Info
> This is a note.

> # Warning
> This is a warning.

The downside of this is that we have to consider the existing heading level hierarchy. This may be able to be bypassed by using headings within sections, but as Markdown originally did not include sections, that would be a non-trivial change to how rendering works.

Supporting multiple languages would indeed be a challenge. But is this any different from the optional info string used in code blocks (already adopted in the CommonMark spec)? In the case of code blocks, to render them correctly you need an additional library that understands how to render the block nicely for the specified language.

The PowerShell documentation team at Microsoft uses a similar extension for admonitions, closer to @Crissov 's suggestion:

> [!NOTE]
> Information the user should notice even if skimming.

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

> Essential information required for user success.

> Negative potential consequences of an action.

> Dangerous certain consequences of an action.

A while ago in McFoggy/commonmark-ext-notifications I used the following syntax:

! This is an info message.
!v This is a success message.
!! Consider this a warning.
!x This is an error message.

that could be rendered like

This syntax was chosen to be simple and self explaining, an exclamation mark character is used to start the admonition block.

  • without any additional charcater, simple info message
  • with v, which looks like checkmark, it is a success message
  • with an additional ! it is a warning
  • finally with a cross, a x character, it denotes an error

Easy to remember.

Emojis or abstract symbols like (!) are a better approach to i18n.

But are the relevant emoji all available? U+2139 [:information_source:] for “Note” and U+26A0 [:warning:︎] for “Warning” exist, but that gets ad-hoc when extended: U+1F4A1 [:bulb:] for “Tip”? U+2621 [☡] or U+26D4 [:no_entry:] for “Caution”?

I didn’t say all useful emojis already existed or that associations were obvious. :relieved:

For instance, there may not be a good red cross/saltire for Error/Caution messages:

  • :x: is traditionally not okay, the opposite of :o:, likewise :person_gesturing_no: and :person_gesturing_ok:, as well as :ng: and :ok:.
  • :negative_squared_cross_mark: is more a tick mark, much like the check mark :white_check_mark:, and not a cancellation or warning sign.
  • :heavy_multiplication_x: is a multiplication operator.

For the distinction between Warning, Note and Important or Information, there are :information_source:, :warning:,:exclamation:and​:grey_exclamation:.

From Unicode.org, Emoji List, v14.0:

Code Sample CLDR Short Name Other Keywords
1523 U+2139 ℹ information i | information
1377 U+26A0 ⚠ warning warning
1380 U+1F6AB 🚫 prohibited entry | forbidden | no | not | prohibited
1488 U+274C ❌ cross mark × | cancel | cross | mark | multiplication | multiply | x
1469 U+203C ‼ double exclamation mark ! | !! | bangbang | double exclamation mark | exclamation | mark
1474 U+2757 ❗ red exclamation mark ! | exclamation | mark | punctuation | red exclamation mark
1471 U+2753 ❓ red question mark ? | mark | punctuation | question | red question mark
1485 U+2705 ✅ check mark button ✓ | button | check | mark
920 U+1F6A7 🚧 construction barrier | construction
1213 U+1F4A1 💡 light bulb bulb | comic | electric | idea | light
1028 U+2728 ✨ sparkles * | sparkle | sparkles | star
1158 U+1F4E2 📢 loudspeaker loud | loudspeaker | public address
1263 U+1F4DD 📝 memo memo | pencil
1 Like

Relevant here are the arguments for and against using the Unicode bullet character:

If the arguments for only using plain ascii characters easily typed on a physical keyboard are strong they’ll apply here too.

As I wrote on the GitHub.com discussion:

It’s time to move beyond ASCII and English

I think ASCII should no longer have the special status that it has had:

  • It’s very English centric
  • Unicode now has ubiquitous support across apps and platforms.
  • Emoji/symbol entry has been made easy and commonplace.

At the very least english words or words of any language should not become part of the grammar/syntax. If we must stick to ASCII, then "abstract symbols like (!)" as @Crissov suggests would be better.

And for graceful degradation, as well as for the semantics, I think using ATX headings make a lot of sense, as you brought up before. Here is the same example from the GitHub.com discussion, but using ASCII instead:

> # (!) Do not feed the dragons!
> Unless you:
> - are properly supervised by children.
> - are wearing dragon pajamas
> - feed them pancakes

will render under legacy Markdown/CommonMark as:

(!) Do not feed the dragons!

Unless you:

  • are properly supervised by children.
  • are wearing dragon pajamas
  • feed them pancakes

and under tools that recognize the admonition syntax as an HTML div with an admonition class.

I’m don’t understand your earlier statement:

A block quote represents a sectioning root. This is true in HTML. I think it is implied in Markdown because of the semantics of a block quote: content from elsewhere. Thus the headings in a block quote are in a separate scope from the content that it is embedded within. You’ll never see headings within a block quote appear within the table of contents, for example.

@jgm What is your opinion on all this? It matters much as I think the GitHub folks will listen to you far more than they will to us. They are barreling ahead with what will become a de facto Markdown standard given their reach and power.