Image Icons Mode

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

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

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:

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

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

For example:

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

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:

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.