Image Icons Mode

Setting the icons attribute to image (or leaving it empty) instructs the AsciiDoc processor to use images for icons. This page defines where the processor looks for these image files by default, which image file extension it prepends, and how to configure both.

Enable image-based icons

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

= Document Title
:icons: image

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

Default icons directory and type

By default, the AsciiDoc processor will look for icons in the icons directory relative to the value of the imagesdir attribute. If you have not configured either attribute, that path resolves to ./images/icons.

The processor won’t look for icons of any type (i.e., format). Instead, it will look for icons that have the .png file extension.

Let’s assume you have the following NOTE admonition block in your document:

NOTE: Remember the milk!

The AsciiDoc processor will resolve the admonition icon to ./images/icons/note.png.

Configure the icons directory using iconsdir

To change where the AsciiDoc processor looks for icons, you can specify a different location using the iconsdir attribute.

For example:

= Document Title
:icons: image
:iconsdir: icons

When converting this document, the AsciiDoc processor will look for images in the icons directory instead of the default ./images/icons.

Configure the icon type using icontype

If the icon path is derived, such as for an admonition icon or if the target of the icon macro does not have a file extension, the AsciiDoc processor will use the icontype attribute to determine which image type (i.e., format) to look for. By default, the value of this attribute is png, so the processor will look for an image with the file extension .png.

You can use the icontype document attribute to configure the default icon type.

For example:

= Document Title
:icons: image
:icontype: svg

For NOTE admonitions, the AsciiDoc processor will now look for the image note.svg in the iconsdir instead of note.png.

The value of the icontype attribute is ignored for the icon macro if the target has a file extension. It’s only used when the icon type must be inferred.