Add support for admonitions

[kipcole9]

Feature request to add support for ex_docs-style admonitions in the markdown renderer.

[jonatanklosko]

Hey Kip! GitHub Markdown doesn't support admonition blocks, so I'm not sure if we should support it, especially that .livemd files will be rendered as Markdown on GitHub soon (I think). @josevalim wdyt?

[kipcole9]

@jonatanklosko yes, Markdown hardly a formal standard for sure.

My 2c is that the power of Liveview is not upcoming rendering in Github, but attaching it to a live running Elixir instance. And in these cases, as I start building tutorials and presentations, I believe that admonitions would be incredibly useful to emphasise key points, breakup up a document making it easier to read and deliver an overall better experience.

Admonitions are, after all, valid Markdown markup. Just not very pretty if rendered with an engine that doesn't support them.

Short version: I think ex_doc earmark is the better "standard" for Elixir, not GFM. (And I say that as someone who wishes earmark supported GFM check boxes :-))

[kipcole9]

BTW, really awesome work @jonatanklosko, such an amazing addition to the Elixir ecosystem. I'm giving my first ever ElixirConf presentation this Friday - and its all in Livebook.

[josevalim]

There are two issues here: we need to support special classes AND support IAL notation from kramdown, and I am not comfortable with making both choices right now.

GitHub is considering their own syntax now, which I dislike, so I would like to wait a bit more before we make an official move. :)

[christhekeele]

Update from looking into this again recently: in our year of the lord 2024, it looks that that discussion has borne fruit! GitHub has shipped support for several admonitions. Check it out to see the kitchen sink, they've updated the discussion description and they look quite nice.

Is it perhaps time to consider re-opening this, or discussing some ecosystem-wide unification effort?

---

GitHub is considering community/community#16925, which I dislike

It looks like they may have changed the syntax since you last looked at it, from:

> **Note**
> This is a note

to

> [!NOTE]  
> 
> This is a note

Personally, I really like this implementation.

One original design goal of markdown is to look sensible when not rendered via anything special at all. Obviously, the current ex_doc "styled" syntax (#### Error {: .error}) via special classes and IAL notation does not really do that; see the comparisons below.

The current GH "semantic" syntax ([!ERROR]), on the other hand, extends markdown with a new concept that if not supported by the renderer, still does a good job of looking like an importantly titled blockquote header you cannot easily scan past without noticing (similar to naming your read-me.txt file README.txt instead).

On the other hand, the current GH syntax does not support custom admonition titles, and they are definitely working through some edge cases still, so it may be a bit premature.

---

Comparison

Here's how the tutorial ex_doc admonitions look side-by-side with the GFM ones; for a livemd file rendered in:

Plain text

(vsCode custom theme markdown highlighting)

ExDoc v0.32.1

Livebook v0.12.1

GitHub

Error {: .error}

This syntax will render an error block

Warning

Critical content demanding immediate user attention due to potential risks.

[josevalim]

I wrote my feedback here: https://github.com/orgs/community/discussions/16925

Opposite to ExDoc, whatever GitHub chooses will have a large impact, and I still think their proposal goes against the original goals behind Markdown. :(

[christhekeele]

Those are very good counter-points and I like your proposal more than any syntax to date. Hope it gains traction!