Image Icons Mode
icons attribute to
image (or blank) 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.
To enable image-based icons, you set the
icons attribute in the document header to the value
= 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.
By default, the AsciiDoc processor will look for icons in the icons directory relative to the value of the
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.
To change where the AsciiDoc processor looks for icons, you can specify a different location using the
= 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.
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
You can use the
icontype document attribute to configure the default icon type.
= 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.