blog

Admonitions in Markdown

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

2 min read / 2 Nov 22

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.

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.