Adding Admonitions to Jekyll

• Adam Douglas

• Published Sep 22, 2022
• Revised Jan 10, 2023

• web
• #100DaysToOffload #jekyll #webdev

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.

{% if include.type.size > 0 and include.title.size > 0 and include.body.size > 0 %}
    {% assign types = "note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote" | split: ", " %}
    {% if types contains include.type %}
<div class="admonition {{ include.type }} rounded">
    <p class="admonition-title">{{ include.title }}</p>
    <p>
        {{ include.body }}
    </p>
</div>
    {% endif %}
{% endif %}

$primary-color: #fc0;
$primary-bgcolor: rgba(55.59%, 44.41%, 0%, .4);
$admonitions:
    //class (type), icon filename, icon/border color, title bg color
    ('note', 'pen-solid.svg')
    ('abstract', 'align-left-solid.svg')
    ('info', 'info-circle-solid.svg', '#00b0ff', '#293d52')
    ('tip', 'fire-solid.svg', '#ff9100', '#433a38')
    ('success', 'check-circle-solid.svg', '#00c953', '#294040')
    ('question', 'question-circle-solid.svg', '#00b8d4', '#293e4e')
    ('warning', 'exclamation-triangle-solid.svg', '#ff9100', '#564b3c')
    ('failure', 'times-circle-solid.svg', '#ff5252', '#564444')
    ('danger', 'bolt-solid.svg', '#ff1744', '#563e43')
    ('bug', 'bug-solid.svg', '#f50057', '#553c45')
    ('example', 'list-ol-solid.svg', '#9e9e9e', '#4c4c4c')
    ('quote', 'quote-right-solid.svg', '#9e9e9e', '#4c4c4c')
;
.admonition {
	margin: 1.5625em 0;
	overflow: hidden;
	color: #808080;
	page-break-inside: avoid;
	background-color: #212121;
	border-left: .3rem solid $primary-color;
	border-radius: .1rem;
}
.admonition p {
    padding: 0 1rem;
}
.admonition .admonition-title {
    color: #ddd;
    background-color: $primary-bgcolor;
    font-weight: 700;
    line-height: 3rem;
}
.admonition-title::before {
    margin-right: .5rem;
    width: 1.2rem;
    height: 1.2rem;
    display: inline-block;
    content: '';
    -webkit-mask-size: cover;
    mask-size: cover;
    background-color: $primary-color;
    vertical-align: text-bottom;
}
@each $name, $icon, $icon-color, $title-color in $admonitions {
    @if $icon-color {
        .admonition.#{$name} {
            border-left-color: #{$icon-color};
        }
    }
    @if $title-color {
        .admonition.#{$name} .admonition-title {
            background-color: #{$title-color};
        }
    }
    .admonition.#{$name} .admonition-title::before {
        -webkit-mask: url("/assets/img/icons/#{$icon}") no-repeat 50% 50%;
        mask: url("/assets/img/icons/#{$icon}") no-repeat 50% 50%;
        @if $icon-color {
            background-color: #{$icon-color};
        }
    }
}

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.

{% 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.

This is post 32 of 100, and is round 2 of the 100 Days To Offload challenge.

References

• Admonition word definition, Wordnik
• Admonitions - Material for MkDocs
• Call-out word definition
• CSS, wikipedia
• HTML, wikipedia
• Jekyll Liquid documentation
• Jekyll
• Liquid template language documentation
• Sass (stylesheet language), wikipedia
• Scalable Vector Graphics (SVG), Wikipedia

Changelog

• Jan 4, 2023
  • change topic
• Jan 10, 2023
  • Change 100DaysToOffload message

Comments

Reply via email

Share