Multi-colored admonitions or call-outs repeated horizontally

Adding Admonitions to Jekyll

  • Adam Douglas
  • website

I came across some great admonitions when I installed the theme Material for MkDocs on my website, Adamsdesk Knowledge Base. The admonitions worked out well for me, but I also wanted admonitions for my main website too, Adamsdesk.com. So keep things small yet effective I decided to create my own iteration within Jekyll.

What is an admonition?

A distinct area of text to emphasize significant attention that is not a part of the main body. The purpose of admonition is drawing attention towards what you want a reader to remember without significantly interrupting the document flow. Admonitions are more commonly referred to as a callout or call-out.

The Code

My approach was to create a Jekyll include file for the HTML with Liquid template language and Cascading Style Sheets (CSS) with syntactically awesome style sheets (SASS). This will allow for ease of adding admonitions without having to type out all the code manually each time. The styles are not completely identical to Material as I felt it needed to be more fitting to my theme. The Scalable Vector Graphics (SVG) icons I used are from Font Awesome Free. However, I believe one could also use SVG Repo.

I’ve tested this code on multiple web browsers without issues, so it should work fine under most circumstances.

Assumptions

  • General understanding of using a Linux terminal (command-line interface)
  • ~ (tilde) represents the $HOME (/home/username) of the current user when using BASH
  • Steps prefixed with a “$” (dollar sign) represents the CLI (command-line interface) prompt
  • Steps prefixed with a “#” (number sign) represents the CLI prompt with elevated user permissions (e.g. root)
  • The text after the “$” or “#” is to be entered at the CLI
  • Jekyll is already installed and configured
  • The directory “project” represents the root of the website

Add Admonitions to Jekyll

  1. Install the admonition.html file to the _includes/ directory.
    $ mv ~/Downloads/admonition.html /project/_includes/
    
  2. Install the admonition.scss file to the _sass/ directory.
    $ mv ~/Downloads/admonition.scss /project/_sass/
    
  3. Edit style sheets to import admonition styles.
    $ nano /project/assets/css/styles.scss
    
    @import "admonition";
    
  4. Add admonition icons.
    $ mv ~/Downloads/*.svg /project/assets/img/icons/
    
    pen-solid.svg
    align-left-solid.svg
    info-circle-solid.svg
    fire-solid.svg
    check-circle-solid.svg
    question-circle-solid.svg
    exclamation-triangle-solid.svg
    times-circle-solid.svg
    bolt-solid.svg
    bug-solid.svg
    list-ol-solid.svg
    quote-right-solid.svg
    

Usage

Adding an admonition to a post or page is a simple line of Liquid code. See the example of an info admonition below.

1
{% include admonition.html type="info" title="Info" body="This is information intended to draw attention." %}

Parameters

All three parameters are required in order to render an admonition and have values which has a character length greater than zero (0). The type parameter must be valid value, see parameter values.

type
Specifies the rendering style of admonition.
title
The heading text displayed at the top of the admonition.
body
The primary message displayed in the body area of the admonition.

Parameter Values

Type

Must be one of the following values. If an invalid type value is provided the admonition will not be rendered.

  • abstract
  • bug
  • danger
  • example
  • failure
  • info
  • note
  • question
  • quote
  • success
  • tip
  • warning

Title

A string value that must have a length greater than zero (0). No maximum length.

Body

A string value that must have a length greater than zero (0). No maximum length.

Rendered Examples

Note

Well look at you reading this admonition.

Abstract

Abstract can be difficult to understand.

Info

This is very informative, would you not agree?

Tip

Add this admonition to level up your website.

Question

What is the question again?

Success

I was successful in making you read this message.

Failure

Failure is a part of the learning process.

Warning

Due to unpopular belief, most warnings go unnoticed with exception to this one.

Danger

Reading this website may result in growing your knowledge.

Bug

This article may contain a bug, or it may not.

Example

This is an example of the admonition example.

Quote

Reading an admonition a day keeps the bad code away.