Feature Request: Admonitions in CommonMark?

Spec
1

As someone that uses CommonMark flavoured MarkDown to write documentation for output in many formats, my biggest pain point is the inability to insert admonitions in a standard way.

I find admonitions to be very useful in user-focused documentation:

  • They pull the user’s attention to important information (notes, warnings, errors, etc.)
  • They prevent the abuse of blockquotes in ways like:
> **Note**: This is a note

> **Warning**: This is a warning. Pay attention to this text.

I’m personally a big fan of the python-markdown/mkdocs admonition syntax; it preserves the ability to produce “easy-to-read and easy-to-write plain text”.

!!! type "optional explicit title within double quotes"
    Any number of other indented markdown elements.

e.g.:

!!! note
    This is a note admonition.

I’m aware that I could write a Pandoc filter (etc.) that will enable me to use this syntax in my documentation, but I honestly believe that extending CommonMark to include admonitions is something benefits a large group of CommonMark users, MarkDown users in general (indirectly), and as a happy side-effect, also works to prevent egregious abuse of blockquotes.

I’d love to see some thoughts from the community around standardising admonitions, as there are a few extensions out there that have taken the python-markdown/mkdocs syntax and modified it, and Pandoc filters that use a different syntax entirely!

Defining a standard for admonitions would help bring these into alignment and help make MarkDown more portable between flavours.

I’m also aware that adding admonitions to the CommonMark specification won’t magically make everything support them. It will, however, make it easy to implement across editors and conversion programs as there’s a standard syntax for generating them.

Thanks for your time!

1 Like
2

You should search the forum. Admonitions have most certainly been discussed before. Also Pandoc, Markdown-It and other CommonMark compatible renderers support Admonitions and other kinds of custom blocks via options or plugins.

As to adding new features to the base CommonMark specification itself, there doesn’t seem to be appetite to do so at the moment. The focus, with some small exceptions, has been to standardize basic Markdown. This hasn’t changed in the many years of feature requests that have been made (again, search the forums and you’ll see many robust debates on new features and syntax). Not trying to discourage you… Just setting expections :slight_smile:

1 Like
3

Not trying to discourage you… Just setting expections.

I appreciate the feedback. I’m still interested in discussion around syntax (etc) for my own information, at the very least, and to gauge the community’s receptiveness towards admonitions.

My expectations aren’t set too high, but the squeaky wheel gets the grease, and I’m not in a hurry!

4

except when there are dozens if not hundreds of squeaky wheels :wink:

This won’t find all admonition discussions, but for starters: Search results for 'warning' - CommonMark Discussion

1 Like
5

I typically do this with the warning or megaphone emoji inside a blockquote:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse ultricies eleifend dolor, tempus auctor est euismod vel. Aliquam eu purus eu nunc sodales lacinia. Mauris tincidunt iaculis eros, a tincidunt nunc finibus sit amet. Donec ornare nisl lorem, sit amet dictum sem volutpat id. Fusce condimentum vel nisl at sodales. Maecenas vel ipsum euismod, ornare diam in, rutrum odio. Donec vel porttitor magna. Duis eget suscipit odio. Duis fringilla diam in risus faucibus, a consectetur nunc feugiat. Duis sollicitudin dolor lacus. Maecenas facilisis tincidunt nisl at bibendum. Nulla facilisi. Ut vehicula, eros nec gravida posuere, nibh augue elementum augue, at accumsan purus lorem ac ex.

:warning: Here be dragons

Mauris ornare, mauris at porttitor finibus, sem orci pulvinar enim, sed posuere nibh est quis orci. Pellentesque porta purus at mi placerat lacinia. Maecenas et imperdiet mi. Sed commodo maximus turpis sed sollicitudin. Vestibulum magna nisl, sagittis at ipsum at, ultricies luctus tortor. Nulla sed elementum eros. Integer tincidunt mattis dictum. Integer at fringilla augue, quis imperdiet neque. Aenean consequat sodales vulputate. Nunc erat dolor, posuere eu sodales sed, rhoncus vel mauris. Mauris eu eros in sem cursus ornare nec at augue. Sed sit amet libero dolor. Maecenas non volutpat massa. Maecenas sagittis metus eu nibh efficitur, at sodales est semper.

:mega: Note that the above is generic lorem ipsum text for contrast

1 Like
6

Thanks for the response!

I agree that emoji within a blockquote is eye-catching, but (IMO) this falls into the ‘egregious abuse of blockquotes’ category.

According to the HTML5.2 specification:

The blockquote element represents content that is quoted from another source…

Content inside a blockquote other than citations and in-line changes must be quoted from another source, whose address, if it has one, may be cited in the cite attribute.

So, using blockquotes to create admonitions (those that end up in HTML output, at least) is a violation of the HTML specification. It also causes issues with WCAG compliance, as using blockquotes to set indentation (etc) is specifically disallowed, which is basically what we’re doing by abusing blockquotes to create adomonitions. This causes issues with assistive technologies (screen reading software, etc.)

7

That’s why it’s not official. It’s simply a very functional hack that works in many circumstances (e.g. a GitHub README), albeit as you point out it may not work for those reliant on assistive tech.

As I noted earlier, there are solutions that produce proper HTML, solutions that are extensions of CommonMark as well tool-specific solutions (e.g. most static site generators that support Commonmark have a way of doing admonitions). They are just not part of the base CommonMark spec.

Believe me, I’m mostly on your side. But there are arguments for leaving CommonMark as-is, that it was never meant to be the source code for all the possible things you can express in HTML. Take a look at the complexity of DocBook. What if Markdown/CommonMark is only meant for the vast majority of simple documents, and not be DocBook or FrameMaker or a more user friendly Latex?

I may have another solution for you in a couple of months. It’s called TextPlain :wink:

2 Likes
8

As there are those days some buzz around github announcing “kind of” admonitions I reached again this thread so beforehand sorry to revive it.
But in case you really were looking for a commonmark extension that you can use then feel free to look at GitHub - McFoggy/commonmark-ext-notifications: commonmark plugin handling mardown notifications messages which uses an easy to remember syntax for those admonitions.

All admonitions start with ! and depending on their type a second characater is used

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

See the link above for rendering.

1 Like
9

:triangular_flag_on_post: Woops, the first version of this reply confused @McFoggy with @Kangie.

Not bad. I think some people will like this. For me, these admonitions don’t stand out well enough in the plain text, not only as distinct from paragraphs, but as admonitions, which by definition must stand out.

Another desirable feature for Markdown extensions is graceful degradation.

! This is an info message. This is how it degrades when rendered without benefit of the extension.

It kinda-sorta looks like an admonition? What if it’s not surrounded with blank lines, as in your examples? It does better on Disqus (which preserves line breaks) but gets absorbed into the adjacent paragraph in most other places (e.g. GitHub README’s):
!x This is an error message. It does not degrade gracefully if you forget to surround it with blank lines.

So what if instead, your extension uses @codinghorror’s preferred syntax (one that I and many others use as well)? It is not “an egregious abuse” of block quotes, since you are defining a syntax, and as such it is no longer a block quote, and since your extension would render it as an HTML div with an admonitions class, so it is not an abuse of HTML either.

It degrades extremely gracefully, even when nested:

It supports admonition headings and arbitrary Markdown content:

:warning: Do not feed the dragons

Unless you:

  • are properly supervised by children.
  • are wearing dragon pajamas
  • feed them pancakes
And very importantly,

> 🚩 it looks like an admonition in plain text form

This syntax will be supported by Textplain (wow, I said “a couple of months” nearly 2 years ago. Yikes!) and Plain Text Stylesheets (by the end of the year, I promise!). But I encourage you to consider it for your extension. A lot of people already do this. You can find this syntax on GitHub README’s. The more this form is adopted, the more it becomes a de facto standard :wink:

An alternative, if you prefer to overload paragraphs instead of block quotes, is to use Unicode emoji instead of or in addition to ASCII markers:

ℹ️ This is an info message.
✅ This is a success message.
⚠️ Consider this a warning.
❌ This is an error message.

I used symbols paralleling your HTML rendering.

:triangular_flag_on_post: I think ASCII should no longer have the special status that it has had: It’s very English centric, everyone now supports Unicode, and emoji entry has been made easy and commonplace.

1 Like
10

See GitHub’s new format: [Markdown] An option to highlight a "Note" and "Warning" using blockquote (Beta) · community · Discussion #16925 · GitHub

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.
1 Like
11

[!RUBBISH]
should render with a trash can icon :wastebasket:

1 Like