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.
<target> is the icon name or path.
<attrlist> specifies various named attributes to configure how the icon is displayed.
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.
<div class="paragraph"> <p><span class="image"><img src="./images/icons/tags.png" alt="tags"></span> ruby, asciidoctor</p> </div>
Here’s how the DocBook converter converts an icon macro.
<inlinemediaobject> <imageobject> <imagedata fileref="./images/icons/tags.png"/> </imageobject> <textobject><phrase>tags</phrase></textobject> </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.,
The icon name will be resolved to a file in the
iconsdirwith the file extension specified by
The icon name will be resolved to a glyph in an icon font (as mapped by a CSS class) (e.g.,
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.,
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
linkattribute is specified).
Here’s an example of an icon that uses a role to specify the color.
icon:tags[role=blue] ruby, asciidoctor
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:
Rotates the icon; values:
Flips the icon; values:
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