Asciidoctor Admonition Icons Missing

Been writing some reference documents in my new ‘best friend’ – the asciidoctor markup syntax. For some time now i get puzzled when i want an admonition icon to appear in my document but it won’t. Ok my markup looks good to me and i have installed the ruby asciidoctor version:

jnorthr@jnorthr-EC548AA-ABU-a1128-uk:~/Desktop$ asciidoctor -V
Asciidoctor 0.1.4 []

So a typical document like this works fine except that the beautiful image icons do not show up. I thought at first i had to lug around a folder of ./images/icon/*.png and all that stuff but it irked me somewhat.

My text of

= Notes About Asciidoc Sample Applications
jnorthr <>
v1.0, 2014-06-01 updated 7 June 2014

:icons: font

NOTE: Asciidoctor now supports font-based admonition icons, powered by Font Awesome!

== Overview

Caelyf lacks a template servlet for markup documents written using the asciidoctor markup syntax.

== Sample Application

You can find most of our sample applications on our github anynines account at[]. 

WARNING: You will need to signup with a cloud foundry PaaS provider before running any of these samples.

looks ok and renders as html quite nicely.



So that’s not what i need is it ? Where are my awesome icons ? Well, it turns out that i needed to add a bit of code to pull down the awesome.css stylesheet that has all the magic. So on the line just above

:icons: font

I added a passthru comment that renders in the final html document. That passthru comment looks like:


v1.0, 2014-06-01 updated 7 June 2014

<link rel="stylesheet"  href="">

:icons: font

So we need an external css link specification between the document date line and the icons font line. See my <LINK code above, and yes you do need to include ++++ lines above and below it too.

If you put that line into your .adoc script, so should experience the joy and pleasure of visible awesome fonts for all asciidoctor admonitions !   🙂



Install Asciidoctor Command Line Tool – Part Three

If you need background as to why i had to do this, read about this in part one.

If you need to install ruby or the gem manager on your windows XP system, then read about it in part two.

You need ruby and the gem manager on your XP system before you can install the asciidoctor gem. If you’ve followed my previous post, by now you should have a ruby devkit on your C:\ drive and you will need to have changed into your devkit folder, before you run the gem install command below :

// --------------------------------
$ dir
HP_Owner@HP-PAVILLION c:\devkit >
$ gem install asciidoctor --platform=ruby
Fetching: asciidoctor-0.1.4.gem (100%)
Successfully installed asciidoctor-0.1.4
1 gem installed
Installing ri documentation for asciidoctor-0.1.4...
Installing RDoc documentation for asciidoctor-0.1.4...

Confirm Success

Now it’s time to confirm we’ve successfully installed this gem, so see the following joblog from my install session :

$ asciidoctor -v
Usage: asciidoctor [OPTION]... FILE...
Translate the AsciiDoc source FILE or FILE(s) into the backend output format (e.g., HTML 5, DocBook 4.5, etc.)
By default, the output is written to a file with the basename of the source file and the appropriate extension.
Example: asciidoctor -b html5 source.asciidoc

-v, --verbose enable verbose mode (default: false)
 -b, --backend BACKEND set output format backend (default: html5)
 -d, --doctype DOCTYPE document type to use when rendering output: [article, book, manpage, inline] (default: article)
 -o, --out-file FILE output file (default: based on input file path); use - to output to STDOUT
 --safe set safe mode level to safe (default: unsafe)
 enables include macros, but restricts access to ancestor paths of source file
 provided for compatibility with the asciidoc command
 -S, --safe-mode SAFE_MODE set safe mode level explicitly: [unsafe, safe, server, secure] (default: unsafe)
 disables potentially dangerous macros in source files, such as include::[]
 -s, --no-header-footer suppress output of header and footer (default: false)
 -n, --section-numbers auto-number section titles in the HTML backend; disabled by default
 -e, --eruby ERUBY specify eRuby implementation to render built-in templates: [erb, erubis] (default: erb)
 -C, --compact compact the output by removing blank lines (default: false)
 -a key[=value],key2[=value2],...,
 --attribute a list of document attributes to set in the form of key, key! or key=value pair
 unless @ is appended to the value, these attributes take precedence over attributes
 defined in the source document
 -T, --template-dir DIR a directory containing custom render templates that override the built-in set (requires tilt gem
 may be specified multiple times
 -E, --template-engine NAME template engine to use for the custom render templates (loads gem on demand)
 -B, --base-dir DIR base directory containing the document and resources (default: directory of source file)
 -D, --destination-dir DIR destination output directory (default: directory of source file)
 --trace include backtrace information on errors (default: false)
 -h, --help show this message
 -V, --version display the version


Look for the asciidoctor version number in the details. Ok, i used the wrong option as -v should have been uppercase as -V so try that and you should see something similar to this :

Asciidoctor 0.1.4 []

Nice one ! 🙂