blog

Admonitions in Markdown

Working or failing gracefully across Apostrophe, Kramdown, and Jekyll. No plugins required.

Lawrence Murray 2 November 2022

Admonitions are the asides used in technical writing and documentation for remarks, tips, examples, cautionary notes and the like:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

There is no standard syntax for these across Markdown variants. Python-Markdown supports syntax of the form:

!!! tip
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

This can be used in MkDocs documentation and rendered beautifully by the MkDocs Material theme. On the other hand, the CommonMark specification does not include admonitions, nor Kramdown—the default Markdown processor of Jekyll, as used on this site—nor Apostrophe, my editor of choice.

Blockquotes, however, are universally supported across the above with the syntax:

> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

With Kramdown, this renders in HTML as:

<blockquote>
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
</blockquote>

displaying in the browser as the first, generic, example at the top.

The trick for the non-generic variants is to use Kramdown’s block attributes to assign a different class to each, using the syntax {:.example} after the blockquote:

> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
{:.success}

> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
{:.danger}

> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
{:.warning}

> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
{:.info}

This produces HTML output where a class attribute is added to each blockquote:

<blockquote class="success">
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
</blockquote>

<blockquote class="danger">
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
</blockquote>

<blockquote class="warning">
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
</blockquote>

<blockquote class="info">
  <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
</blockquote>

These render in the browser as at the top. In Apostrophe, and perhaps other editors, the block attributes have no effect but render invisibly in the preview as a graceful fail.

Now to style. This site uses a custom Bootstrap theme developed by working with source files with SCSS. The following code is added to the customized SCSS source file to have blockquote elements extend Bootstrap’s alert components, as well as add icons and other tweaks. This can be adapted for other themes.

blockquote {
  @extend .alert;
  @extend .alert-primary;
  @extend .pb-0;
  font-size:15px;
}

blockquote.success {
  @extend .alert-success;
}
blockquote.success p:before {
  content: "✓ Success ";
  font-weight:bold;
  font-size:16px;
}

blockquote.danger {
  @extend .alert-danger;
}
blockquote.danger p:before {
  content: "⊠ Danger ";
  font-weight:bold;
  font-size:16px;
}

blockquote.warning {
  @extend .alert-warning;
}
blockquote.warning p:before {
  content: "⚠ Warning ";
  font-weight:bold;
  font-size:16px;
}

blockquote.info {
  @extend .alert-info;
}
blockquote.info p:before {
  content: "ⓘ Further Information ";
  font-weight:bold;
  font-size:16px;
}

The end result is that admonitions can be written as blockquotes with block attributes when editing, displayed as generic blockquotes in Apostrophe while previewing, and rendered as admonitions in the browser once published.

blog Latest
GPU Programming in the Cloud
How to develop on remote cloud instances, and a roundup of cloud service providers.

Lawrence Murray

22 Nov 22

GPU Programming in the Cloud
blog Related
Open Source Alternatives for Two Factor Authentication (2FA) Across Multiple Devices
Gnome Authenticator for Desktop, Aegis Authenticator for Android, import and export between.

Lawrence Murray

10 Nov 22

software Next
Jekyll Responsive Magick
A Jekyll plugin for responsive images using ImageMagick. Works with Jekyll 4.
blog Previous
Responsive Images with Jekyll and ImageMagick
Step by step through the HTML, ImageMagick and Ruby. Works with Jekyll 4.

Lawrence Murray

30 Oct 22