Admonition Blocks extension

[mhanberg]

Description

It would be great to be able to create admonition blocks, similar to how you can on GitHub

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

> [!TIP]
> Optional information to help a user be more successful.

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

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

> [!CAUTION]
> Negative potential consequences of an action.

On GitHub is currently produces HTML that looks like

<div class="markdown-alert markdown-alert-note" dir="auto">
  <p class="markdown-alert-title" dir="auto">
    <svg class="octicon octicon-info mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
  Note
  </p>
  <p dir="auto">Highlights information that users should take into account, even when skimming.</p>
</div>

Rendering an SVG is much too opinionated, but I feel that rendering a div with two p tags inside and appropriate class names to style would work well.

I am interested in contributing this feature as long as there is upstream interest, thank you!

[digitalmoksha]

@mhanberg I think it would be great if you want to contribute that. It is on my list to contribute it in the next couple of months if someone else hasn't beaten me to it.

I have thought about it some, so here are a couple thoughts on the implementation.

I think if we can leverage off of the actual block quote parsing, we will actually be able to use an alert anyplace a block quote can be used, which would end up being usable in many more places than the current GitHub implementation. There are quite a few complaints about these limitation in the discussion thread, https://github.com/orgs/community/discussions/16925.

I also think we should allow the overriding of the alert text by allowing any text following the key phrase to be used as the title. For example

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

would use For your attention instead of Note for the title. This has also been mentioned in the discussion thread. It would also help address concerns about not being able to have the alert titles in other languages.

I haven't given it enough thought yet, but I wonder if there isn't a more semantic way to represent it - maybe using a header tag for the title.

[mhanberg]

I'll take a crack, thank you for your thoughts!

[mhanberg]

It turns out that the bindings for comrak that I use (MDEx) introduced a new API that will allow me to implement admonition blocks in user space, so I won't need to work on this for now, but it would obviously be better if it was builtin, in case someone else wants to tackle it!

[digitalmoksha]

Oh cool, glad you can do it in your own context. And thanks for posting back here - I may tackle it when I have some time.

[yonas]

marmite currently uses comrak. Having callouts would be a great feature to have in a blog post.