June 19, 2014

Awesome Asciidoctor: Use Inline Icons

Asciidoctor adds the icon: macro to the Asciidoc markup. With the macro we can insert an icon in our text. We specify the name of the icon after the macro name. If we use an HTML backend together with the document attribute icons set to the value font we can use Font Awesome Icons. If we want to use icon images the icon is looked up in the directory specified by the attribute iconsdir. For example the Docbook backend will use this to insert an icon.

In the following markup we use the icon macro to insert a comment and file icon:

:icons: font

icon:comment[] This is a comment icon

icon:file[] And a file icon

We get the following result:

And the following HTML is generated:

<div class="paragraph">
<p><span class="icon"><i class="icon-comment"></i></span> This is a comment icon</p>

<div class="paragraph">
<p><span class="icon"><i class="icon-file"></i></span> And a file icon</p>

We can specify CSS classes using the role attribute for the macro. But together with the HTML backend and font-based icons we can also use other attributes: size, rotate and flip. The size attribute can specified without the attribute name if we use it as the first attribute:

// Change icon size
icon:comment[4x] This is a comment icon
// Alternative icon:comment[size="4x"]
// Possible values: large, 2x, 3x, 4x, 5x

// Flip and rotate
icon:file[flip="vertical", rotate="180", role="lime"] And a file icon
// Possible flip values: vertical, horizontal
// Possible rotate values: 90, 180, 270

When we generate HTML we get the following result:

When we want to use an inline icon as a link we can use the attributes link and window:

// Use link attribute to specify link.
// Optional window attribute will be the target window.
icon:user[link="http://www.mrhaki.com/about", window="_blank"]

Image based icons have the following attributes, like an image: alt, width, height, title, role.

Code written and generated with Asciidoctor 0.1.4.