Font and Image Icons

Font-based or image icons are enabled with the icons document attribute.

icons attribute

The icons document attribute allows you to replace the default text-based labels for admonitions with font-based icons or images. Setting the icons attribute also enables the icon macro. The icons attribute accepts the following values:

font

To use font-based icons for admonitions and with the icon macro, set the icons attribute and assign it the value font. See Activate font-based icons for details.

image

To use local image files, set the icons attribute and assign it the value image. While the icon macro is enabled when the value is image, it will only produce text-based output.

Alternatively, you can enable the use of fonts during PDF generation by passing the icons attribute to the asciidoctor-pdf command instead setting it in the document header.

$ asciidoctor-pdf -a icons=font -a icon-set=fas sample.adoc

By setting icons, the theme can control the icon used for each type of admonition.

Activate font-based icons

You can enable font-based icons by setting the icons document attribute in the header of your document:

:icons: font

If you want to override the font set globally, also set the icon-set attribute:

:icons: font
:icon-set: fas

You can use font-based icons from any of the following icon sets in your PDF document:

Use of the fa icon set is deprecated. Please use one of the styled FontAwesome icon sets.

The pf icon set is no longer maintained. Prefer the brand icons either from fab or fi instead.

Icon-based fonts are handled by the prawn-icon gem. To find a complete list of available icons, consult the prawn-icon repository.

Insert an icon

Here’s an example that shows how to use the Android icon from the Foundation Icons (fi) icon set in a sentence (assuming the icon-set is set to fi):

:icons: font
:icon-set: fi

Available for icon:social-android[].

You can use the set attribute on the icon macro to override the icon set for a given icon.

:icons: font

Available for icon:social-android[set=fi].

You can also specify the font set using the following shorthand.

:icons: font

Available for icon:social-android@fi[].

It’s a good practice to always specify the icon set in some way.

In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc.), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc.).

:icons: font

icon:android[set=fab,size=40em]

Customize an admonition icon

When icon fonts are enabled, Asciidoctor PDF will replace the label of an admonition with a predefined icon. You can customize the icon per admonition type using a custom theme.

Here’s an example of a theme that shows how to customize the icon for a tip.

custom-theme.yml
extends: default
admonition:
  icon:
    tip:
      name: fas-lightbulb
      stroke_color: #111111
      size: 18

The name consists of an icon prefix (e.g., fas-) followed by the name of the icon in that icon set (e.g., lightbulb). If a category key is not specified for a particular admonition type, Asciidoctor PDF will use the predefined icon for that type.