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:
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 gitbook.com 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:
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).
gitbook-plugin-asciidoc-admonition-icons