Feature Request: Admonitions in CommonMark?

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

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

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!

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

This won’t find all admonition discussions, but for starters: https://talk.commonmark.org/search?q=warning

1 Like

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

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.)

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:

1 Like