I guess implementations could make it multilingual, so the words
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.
> [!NOTE] > Information the user should notice even if skimming. > [!TIP] > Optional information to help a user be more successful. > [!IMPORTANT] > Essential information required for user success. > [!CAUTION] > Negative potential consequences of an action. > [!WARNING] > 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
v, which looks like checkmark, it is a success message
- with an additional
!it is a warning
- finally with a cross, a
xcharacter, 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  for “Note” and
U+26A0 [︎] for “Warning” exist, but that gets ad-hoc when extended:
U+1F4A1  for “Tip”?
U+2621 [☡] or
U+26D4  for “Caution”?
I didn’t say all useful emojis already existed or that associations were obvious.
For instance, there may not be a good red cross/saltire for Error/Caution messages:
- is traditionally not okay, the opposite of , likewise and , as well as and .
- is more a tick mark, much like the check mark , and not a cancellation or warning sign.
- is a multiplication operator.
For the distinction between Warning, Note and Important or Information, there are , ,and:grey_exclamation:.
|№||Code||Sample||CLDR Short Name||Other Keywords|
|1523||U+2139||information||i | information|
|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|
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.
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!
- 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.