djot icon indicating copy to clipboard operation
djot copied to clipboard

Explicit callout/admonition types

Open toastal opened this issue 1 year ago • 31 comments

{.warning}
:::
Watch out!
:::
::: warning
Watch out!
:::

Both of these are listed in the docs. This flexibility is great (especially when compared to folks abusing > blockquote syntax), however, I have some concerns from a higher level where the user doesn't control the renderer and multiple platforms are implementing Djot. If these classes are all ad-hoc and created by each user without required consistency, how will embedded situations be able to make any guarantees about that this block is a warning callout/admonition vs. a regular <div class="warning"> (or whatever non-HTML output it is) so that the renderer can react + style these blocks appropriately? If greater adoption takes place for Djot, it would be good to know that a README.dj could be rendered appropriately on a user's machine, on GitLab/Gitea/SourceHut/etc. Or say I added Djot as a way to compose long-form posts on my hot new ActivityPub social media platform, but my personal blog built with Djot supports only my version of admonitions.

Markdown not having these explicit means you'd have to follow someone else (which locks you into a single platform) or simply have it be unsupported. Admonitions are a common enough pattern that I see NOTE: in like 70% of docs and posts I see and are built into AsciiDoc, reStructuredText, and many Markdown forks (though I also see **NOTE:**, Note:, **Note:**, > **Note**, ℹ️, ℹ️ Note, | Note | |, and I think you see the point). A defined set assures the user an expected output and creates a finite set that the renderer can style appropriately.

For research AsciiDoc supports: NOTE, TIP, IMPORTANT, CAUTION, WARNING

toastal avatar Jan 19 '23 15:01 toastal