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