writing » programming » adding-admonitions

Adding Admonitions

published 02/21/2022 • 2m reading time • 324 views

So first off, what are these ‘admonitions’? Admonitions are a way to add little notes, warnings, or tips to your text.

They aren’t part of normal Markdown, but there are extensions to add support for them in things like docusaurus and mkdocs. I thought It would be cool to add these into my website,,, so that’s what I did.

The Plan

At this point, I wasn’t really sure where to start with this, or even what these things were called. I remembered seeing some in AsciiDoc, so I checked the documentation there. This is where I learned that they are called admonitions.

Searching the term Markdown Admonitions lead to the docusaurus and mkdocs pages linked above. I then had a general idea of what I wanted. I selected 5 admonitions wanted to have.

• Info
• Tip
• Note
• Warning
• Caution

Now to figure out how to do it.

My website uses comrak as the markdown renderer. Comrak supports for modifying the HTML renderer process, but It’s a bit complicated; This is why I decided to stay away from all that and instead decided to implement it in all CSS.

The Implementation

This is the markdown / HTML for one of my admonitions:

<div ad info>
  Title

  Content
</div>

I started by selecting the [ad] attribute and making the background red and rounding the corners (by 4px). Then to add the little FontAwesome icon, I set the content of [ad]:before to be the icon code (Ex: \f05a). I also set the font to be normal normal normal 14px/1 FontAwesome;, which is usually automatically set by the FontAwesome’s fa class.

At this point, I needed to find some colors for all the admonitions. So I did some searching and eventually decided to steal these colors from the Microsoft docs:

The only ‘problem’ was that I was repeating a lot of CSS for each color. So I looked into SCSS Mixins. These let you define reusable CSS code and then call upon it with parameters.

This is the SCSS I ended up with. See it in context on GitHub here.

@mixin admonition($name, $color, $char) {
  & [#{$name}] {
    background: rgba($color, 0.5);
    border-left: solid 5px $color;

    &:before {
      content: $char;
    }
  }
}

.document {
  /* skip */

  & .content {
    /* skip */

    & [ad] {
      margin: 16px 0 16px 0;
      border-radius: 4px;
      padding: 10px;

      &:before {
        font: normal normal normal 14px/1 FontAwesome;
        font-size: inherit;
      }

      & p {
        margin: 10px 0 0 0;
      }
    }

    @include admonition(info, #004173, "\f05a");
    @include admonition(tip, #054b16, "\f0eb");
    @include admonition(note, #3b2e58, "\f249");
    @include admonition(warn, #6a4b16, "\f071");
    @include admonition(caution, #630001, "\f00d");
  }
}

Showcase

I’ve talked so much about them, now let’s see them all!

Conclusion

I think this was a nice little CSS adventure. I learned about SCSS mixins, which I had never used before. Getting a delightful end result and adding another feature to my site is great too :p

In this article, I also tried to add some little visuals (In ## The Implamentation) to show the colors I picked. This is something I will definitely try to do more in the future.