Icon Macro

In addition to built-in icons, you can add icons anywhere in your content where macros are substituted using the icon macro. This page covers the anatomy of the icon macro, how the target is resolved, and what features it support (subject to the icon mode).


The icon macro is an inline macro. Like other inline macros, its syntax follows the familiar pattern of the macro name and target separated by a colon followed by an attribute list enclosed in square brackets.


The <target> is the icon name or path. The <attrlist> specifies various named attributes to configure how the icon is displayed.

For example:



Here’s an example that shows how to inserts an icon named tags in front of a list of tag names.

icon:tags[] ruby, asciidoctor

Here’s how the HTML converter converts an icon macro when the icons attribute is not set or empty.

Example 1. Result: HTML output
<div class="paragraph">
  <p><span class="image"><img src="./images/icons/tags.png" alt="tags"></span> ruby, asciidoctor</p>

Here’s how the DocBook converter converts an icon macro.

    <imagedata fileref="./images/icons/tags.png"/>
</inlinemediaobject> ruby, asciidoctor

When the image for an icon can’t be located in the icons directory, the AsciiDoc processor displays the icon macro’s alt (i.e. fallback) text.

How the icon is resolved

The target of the icon macro is an icon name (or path). How that target is resolved depends on the icon mode assigned to the icons attribute.


The icon name will be enclosed in square brackets (e.g., [heart]).


The icon name will be resolved to a file in the iconsdir with the file extension specified by icontype (e.g., ./images/icons/heart.png).


The icon name will be resolved to a glyph in an icon font (as mapped by a CSS class) (e.g., fa fa-heart).

If you include a file extension in the image target, the icon macro will not work correctly when using the font icon mode (i.e., icons=font).

Icon macro attributes (shared)

The following attributes of the icon macro are shared for all icon modes.


The role applied to the element that surrounds the icon.


The title of the image displayed when the mouse hovers over it.


The URI target used for the icon, which will wrap the converted icon in a link.


The target window of the link (when the link attribute is specified).


Here’s an example of an icon that uses a role to specify the color.

icon:tags[role=blue] ruby, asciidoctor

Here’s an example of an icon with a link that targets a separate window:

icon:download[link=https://rubygems.org/downloads/whizbang-1.0.0.gem, window=_blank]

Icon macro attributes (image mode only)

The attributes listed below only apply when using the image icon mode.


The alternative text on the <img> element (HTML output) or text of <inlinemediaobject> element (DocBook output)


The width applied to the image.

For example, here’s how to control the icon alt text and width when using the image icon mode:

icon:tags[Tags,width=16] ruby, asciidoctor

The icon macro doesn’t support any options to change its physical position (such as alignment).

Icon macro attributes (font mode only)

The icon macro has a few attributes that modify the size and orientation of a font-based icon. These attributes are only recognized in the font icon mode.


First positional attribute; scales the icon; values: 1x (default), 2x, 3x, 4x, 5x, lg, fw


Rotates the icon; values: 90, 180, 270


Flips the icon; values: horizontal, vertical


To make the icon twice the size as the default, enter 2x inside the square brackets.




If you want to line up icons so that you can use them as bullets in a list, use the fw size as follows:

icon:bolt[fw] bolt
icon:heart[fw] heart

Rotate and flip

To rotate and flip an icon, specify these options using named attributes:

icon:shield[rotate=90, flip=vertical]