Font Icons Mode

Setting the icons attribute to font instructs the AsciiDoc processor to select icons from an icon font.

Not all converters support this mode. If a converter does not support this mode, it will fall back to the image mode.

Enable font-based icons

To enable image-based icons, you set the icons attribute in the document header to the value font.

= Document Title
:icons: font

This setting has no affect on the parsing of the AsciiDoc document. It only influences the output generated by the converters.

When converting to HTML, the stylesheet is required in order for the font-based icons to work.

Default icon font

The icon font that is used by default is determined by the processor. Asciidoctor, for example, uses the Font Awesome icon font. You can see the available icons in Font Awesome on the Font Awesome icons page. Using the Font Awesome icons in Asciidoctor requires online access by default.

Default admonition icons

Since the names of admonitions doesn’t necessarily match the names of icons in the icon font, the AsciiDoc processor must map admonition CSS classes to icon names.

When using Font Awesome as the icon set, the following mappings are recommended:

  • note → info-circle

  • tip → lightbulb-o

  • warning → warning

  • caution → fire

  • important → exclamation-circle

Callout numbers and font icon mode

In the font icon mode, callout numbers are displayed as enclosed numbers. However, the icon font is not used to render these glyphs. Instead, they are styled this way using CSS. This is done to allow the range of callout numbers to be open-ended.