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:
>Using blockquotes (MS & Github).
Like @pboling said, I don’t think this is ideal, since an admonition is not a quote.:::Using three colons to start and end a block (Docusaurus & Quarto).
This defines a clear boundary of and admonition block.!!!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.
1 Like
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
by default)
- even with the option to put the url for an icon, using the embedded media syntax (
)
- even with the option to put the url for an icon, using the embedded media syntax (
- 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!'.
> [!] 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.
1 Like
This is a very good point. In other words, it is not graceful at all for the visually impaired.
Does the fault lie with those who fail to use a renderer that translates the overloaded block quote syntax into the appropriate semantic elements in the target format?
Or does it lie with those who enable this failure by creating a syntax that makes it easy to forget about visually impaired readers (e.g. I forgot!)?
If the latter, does that mean that the only way forward is to always extend the syntax, breaking backward compatibility?
Or are there smarter ways to piggyback on existing syntax that is accessibility friendly? For example, using a subheading:
### let's talk about admonitions
(content about admonitions starts here)
#### ⚠️ Using GitHub's Syntax is Bad for Accessibility
(explanation goes here)
🚩 Problem: how do we "exit" this warning block and continue with the regular content?
What if we used fenced code blocks? I assume the info string is read out in screen readers? But it will have a similar screen reader problem to block quote overloading: “code block, info string warning out of info string, [text] out of code block”.
Or maybe just use simple paragraphs prefixed by an icon?
This is a warning block. It should be evident to everyone (sight readers and those who listen to screen readers) because it starts out with a caution symbol. The only limitation is that it can only be a single paragraph.
Or, again, is the only way forward to always extend the syntax and break backwards compatibilty?
Or maybe we define a new “open ended” block type, with something like the info string of fenced code bocks, but which is not defined as a code block?
What about djot’s attribute syntax? How is that read by screen readers, e.g. if by default it translates to a DOM node class attribute?