Awesome Antora: Add icons to admonition labels

Admonitions are a great way to draw the reader’s attention to auxiliary information. Asciidoctor provides five admonition style labels:

  • NOTE

  • TIP




If you are familiar with Asciidoctor, you probably know that you can enable font-based icons using :icons: font. When you do that, Asciidoctor will draw an icon for the built-in admonition labels. And here’s the result with the default stylesheet:

asciidoctor default admonition

It might come as a surprise, but the Antora’s default UI uses its own stylesheet and does not include an icon font. So, using :icons: font will not produce the desired affect:

antora default admonition

Luckily, with a few lines of CSS, we can add the icons back to the admonitions labels.

Supplemental files

Antora provides a feature called "supplemental files" to supercharge the UI. As you can see below, we can define a key named supplemental_files that points to a directory named supplemental-ui:

    url: ''
    snapshot: true
  supplemental_files: './supplemental-ui'

In this directory we will create a CSS file:

.doc .admonitionblock .icon {
    border-radius: 1rem;

i.fa[class^='icon-'], i.fa[class*=' icon-']:before {
    content: "";
    height: 1.25rem;
    width: 1.25rem;
    margin-right: 0.25rem;
    margin-left: -0.5rem;

i.fa.icon-note:before {
    background: no-repeat url("../img/note.svg");

i.fa.icon-tip:before {
    background: no-repeat url("../img/tip.svg");

i.fa.icon-important:before {
    background: no-repeat url("../img/important.svg");

i.fa.icon-warning:before {
    background: no-repeat url("../img/warning.svg");

i.fa.icon-caution:before {
    background: no-repeat url("../img/caution.svg");

Then, create a directory named img in the supplemental-ui directory and add the following SVG icons:

Now, we need to reference this new extra.css file in the <head> of our documentation site by creating a template named head-meta.hbs in a partials directory:

    <link rel="stylesheet" href="{{uiRootPath}}/css/extra.css">

To sum up, your supplemental-ui directory should contain the following files and directories:

├── css
│   └── extra.css
├── img
│   ├── caution.svg
│   ├── important.svg
│   ├── note.svg
│   ├── tip.svg
│   └── warning.svg
└── partials
    └── head-meta.hbs

3 directories, 7 file

And here’s the result:

antora icon admonition

Here, we’ve demonstrated how to add icons next to the admonition labels but you can virtually override the style of any elements by adding CSS rules 🎨