Introducing asciidoc-admonition-icons, a GitBook plugin to restore font icons for AsciiDoc admonition blocks.

I’ve been working hard on the apiman 1.3.x documentation. One nice feature of AsciiDoc/Asciidoctor are admonition blocks; allowing visually clear and categorised emphasis for the important points.

However, at the time of writing this blog, the GitBook AsciiDoc 3.x.x rendering pipeline does not support icons for admonition blocks, providing an inconspicuous, text-only representation:

fbde3670 329f 11e7 9e5a a5a1e716be38.png

There are some PRs and GitHub issues with people trying to get this fixed, but none of them has been merged, so I really wanted to provide an interim solution that would still work on the hosted platform.

Plugin to the rescue.

The solution was to create a simple plugin, asciidoc-admonition-icons [1], that identifies admonition blocks and rewrites the label element to contain the missing glyphs:

46741c22 32a0 11e7 9279 7c7d5d27e280.png

The default styling provides a similar look-and-feel to the Asciidoctor’s standard theme; with FontAwesome icons and a comparable colour scheme. Naturally, you can override both the glyphs and styling.

This should hopefully provide a satisfactory workaround until the GitBook team resolve the issue properly in their codebase.

If you have any problems, please feel free to file an issue.

Installation & Configuration

In your book.json, put asciidoc-admonition-icons in your plugins array

	"plugins": ["asciidoc-admonition-icons"],

Provide your overrides in pluginsConfig.admonitions:

  • The 5 standard AsciiDoc admonition types are available:

  • classes: CSS classes of the admonition icon container.

  • title: HTML title attribute of admonition icon container.

  • content: Unicode value of glyph to use.

The entire set of defaults are shown here for illustrative purposes, but you need only provide those you’re overriding:

Example book.json configuration:

"pluginsConfig": {
    "admonitions": {
        "note": {
            "classes": "fa icon-note",
            "title": "Note",
            "content": "\uf05a"
        "tip": {
            "classes": "fa icon-tip",
            "title": "Tip",
            "content": "\uf0eb"
        "important": {
            "classes": "fa icon-important",
            "title": "Important",
            "content": "\uf06a"
        "caution": {
            "classes": "fa icon-caution",
            "title": "Caution",
            "content": "\uf06d"
        "warning": {
            "classes": "fa icon-warning",
            "title": "Warning",
            "content": "\uf071"

For example, if we were to override the important icon with another glyph:

"important": {
	"classes": "fa icon-important",
    "title": "La baƱera es muy importante!",
    "content": "\uf2cd"

Check out the plugin’s GitBook plugin page, GitHub repo or NPM readme for detailed instructions.

Despite being simple code, quite interesting customisations are possible using a combination of configuration options and CSS. I might add some more sophisticated examples in a future blog post (refer to the docs for some simple ones).

1. Full NPM package name is: gitbook-plugin-asciidoc-admonition-icons
comments powered by Disqus