Admonitions on Joulsen

An admonition is, according to the dictionary, a firm warning or reprimand. But in documentation and the programming world, they are less threatening - they are just some boxes with warnings, info or similar.

I sometimes have to correct some things on my page, or make a small callout, and they are quite useful. Therefore, I created a very minimal admonition that fits with the rest of my website.

Hello

Hej med dig!

With Hugo, articles (like this one) are written in Markdown and converted to HTML before being inserted into templates. These articles cannot (or rather, should not) contain arbitrary HTML and CSS, but there is a way to define these short snippets, such that they can be used in Markdown.

The feature is called a Hugo shortcode, and it is a keyword, which when written in Markdown is converted to corresponding HTML by Hugo. There are a couple of pre-defined shortcodes, such as figure which I use for almost all pictures in my posts. But you can also define your own, place it in layouts/shortcodes/<name> after which you can use it in Markdown by typing {{\<name>}} (no backslash). The shortcode for my admonition is seen below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<div class='admonition admonition-{{ .Get "color" }}'>
    <div>
        <img src='/img/admonition/{{ .Get "icon" }}' class='admonition-icon' alt='{{ .Get "title" }}' />
        <span class="admonition-title">{{ .Get "title" }}<span>
    </div>
    <div class="admonition-content">
        {{- if .Get "content" -}}
            {{ .Get "content" | markdownify }}
        {{- else -}}
            {{- .Inner | markdownify -}}
        {{- end -}}
    </div>
</div>

The different {{ }} elements you see are Go templates. These let you take arguments to the template. For example, the admonition above is produced by the following code:

1
2
3

{{`< admonition title="Hello" color="yellow" icon="smiley.png" >}}
Hej med dig!
{{`< /admonition >}}

Note

In the above example, I had to insert a stray backtick [ ` ] to prevent Hugo from expanding my shortcode.

HTML without CSS is not a pretty sight, so I have a style defined as well. If you want to see the styling, just inspect the admonition in your browser.