@@ -63,6 +63,8 @@ The result of <<ex-block>> is displayed below.
include::example$admonition.adoc[tag=bl-nest]
:icons: font
== Enable admonition icons
In the examples above, the admonition is rendered in a callout box with the style label in the gutter.
You can replace the textual labels with icons by setting the `icons` attribute on the document.
This is how the WARNING admonition paragraph renders when icons is set and assigned the `font` value.
...
...
@@ -79,4 +81,59 @@ The result of <<ex-icon>> is displayed below.
include::example$admonition.adoc[tag=para]
Learn more about using Font Awesome or custom icons with admonitions in xref:macros:icons.adoc[].
Learn more about using Font Awesome or custom icons with admonitions in xref:macros:icons-font.adoc[].
=== Using emoji for admonition icons
If image-based or font-based icons are not available, you can leverage the admonition caption to display an emoji (or any symbol from Unicode) in the place of the admonition label, thus giving you an alternative way to make admonition icons.
If the `icons` attribute is not set on the document, the admonition label is shown as text (e.g., CAUTION).
The text for this label comes from an AsciiDoc attribute.
The name of the attribute is `<type>-caption`, where `<type>` is the admonition type in lowercase.
For example, the attribute for a tip admonition is `tip-caption`.
Instead of a word, you can assign a Unicode glyph to this attribute:
[source]
----
:tip-caption: 💡
[TIP]
It's possible to use Unicode glyphs as admonition icons.
----
Here's the result you get in the HTML:
[source,html]
----
<td class="icon">
<div class="title">💡</div>
</td>
----
Instead of entering the glyph directly, you can enter a character reference instead.
However, since you're defining the character reference in an attribute entry, you (currently) have to disable substitutions on the value.
[source]
----
:tip-caption: pass:[💡]
[TIP]
It's possible to use Unicode glyphs as admonition icons.
----
On GitHub, the HTML output from the AsciiDoc processor is run through a postprocessing filter that substitutes emoji shortcodes with emoji symbols.
That means you can use these shortcodes instead in the value of the attribute:
[source]
----
\ifdef::env-github[]
:tip-caption: :bulb:
\endif::[]
[TIP]
It's possible to use emojis as admonition icons on GitHub.
----
When the document is processed through the GitHub interface, the shortcodes get replaced with real emojis.
This is the only known way to get admonition icons to work on GitHub.
In addition to built-in icons, you can add icons anywhere in your content where macros are substituted using the icon macro.
This page covers the anatomy of the icon macro, how the target is resolved, and what features it support (subject to the icon mode).
== Anatomy
The icon macro is an inline macro.
Like other inline macros, its syntax follows the familiar pattern of the macro name and target separated by a colon followed by an attribute list enclosed in square brackets.
[source]
----
icon:<target>[<attrlist>]
----
The `<target>` is the icon name or path.
The `<attrlist>` specifies various named attributes to configure how the icon is displayed.
For example:
[source]
----
icon:heart[2x,role=red]
----
== Example
Here's an example that shows how to inserts an icon named _tags_ in front of a list of tag names.
[source]
----
icon:tags[] ruby, asciidoctor
----
Here's how the HTML converter converts an icon macro when the `icons` attribute is not set or empty.
Here's how the DocBook converter converts an icon macro.
[source,xml]
----
<inlinemediaobject>
<imageobject>
<imagedata fileref="./images/icons/tags.png"/>
</imageobject>
<textobject><phrase>tags</phrase></textobject>
</inlinemediaobject> ruby, asciidoctor
----
When the image for an icon can't be located in the icons directory, the AsciiDoc processor displays the icon macro's alt (i.e. fallback) text.
== How the icon is resolved
The target of the icon macro is an icon name (or path).
How that target is resolved depends on the xref:icons.adoc#enable-icons[icon mode].
text::
The icon name will be enclosed in square brackets (e.g., `[heart]`).
image::
The icon name will be resolved to a file in the `iconsdir` with the file extension specified by `icontype` (e.g., [.path]_./images/icons/heart.png_).
font::
The icon name will be resolved to a glyph in an icon font (as mapped by a CSS class) (e.g., `fa fa-heart`).
WARNING: If you include a file extension in the image target, the icon macro will not work correctly when using the font icon mode (i.e., `icons=font`).
== Icon macro attributes (shared)
The following attributes of the icon macro are shared for all icon modes.
`role`::
The role applied to the element that surrounds the icon.
`title`::
The title of the image displayed when the mouse hovers over it.
`link`::
The URI target used for the icon, which will wrap the converted icon in a link.
`window`::
The target window of the link (when the `link` attribute is specified).
=== Role
Here's an example of an icon that uses a role to specify the color.
[source]
----
icon:tags[role=blue] ruby, asciidoctor
----
=== Link and window
Here's an example of an icon with a link that targets a separate window:
Setting the `icons` attribute to `font` instructs the AsciiDoc processor to select icons from an icon font.
CAUTION: Not all converters support this mode.
If a converter does not support this mode, it will fall back to the xref:icons-image.adoc[image mode].
== Enable font-based icons
To enable image-based icons, you set the `icons` attribute in the document header to the value `font`.
[source]
----
= 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.
IMPORTANT: 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 {url-fontawesome-icons}[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
////
TODO: move to Asciidoctor
== Default font-based admonition icons
When font-based icons are enabled, Asciidoctor will draw the icons for the 5 built-in admonition types using Font Awesome.
To use the default font-based admonition icons for admonitions, set the value of the `icons` document attribute to `font` in the document header.
[source]
----
= Document Title
:icons: font
NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
----
// We need to explain that the default admonition icons have different names (i.e., `icon-note` instead of `fa-note`, because they're built in to the stylesheet.
Asciidoctor will emit HTML markup that selects the appropriate font character from the Font Awesome font for each admonition block.
For instance, Asciidoctor selects the Font Awesome icon `icon-note` for `NOTE` admonition blocks.
.Result: HTML output when the icons attribute is set to font
[source,html]
----
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
</td>
</tr>
</table>
</div>
----
This is how the admonition looks rendered.
NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
The icons chosen are selected by the stylesheet.
The default stylesheet maps icons to the following 5 CSS classes:
* .admonitionblock td.icon .icon-note
* .admonitionblock td.icon .icon-tip
* .admonitionblock td.icon .icon-warning
* .admonitionblock td.icon .icon-caution
* .admonitionblock td.icon .icon-important
If you want to customize the icon or the color that is used, you'll need to provide a custom stylesheet or override the styles using a docinfo file.
Here's an example that shows how to change the icon for the note admonition to sticky note:
[source,css]
----
.admonitionblock td.icon .icon-note::before {
content: "\f24a";
color:black;
}
----
////
== Callout numbers
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.
Setting the `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.
== Enable image-based icons
To enable image-based icons, you set the `icons` attribute in the document header to the value `image`.
[source]
----
= 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 [.path]_icons_ directory relative to the value of the `imagesdir` attribute.
If you have not configured either attribute, that path resolves to [.path]_./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:
[source]
----
NOTE: Remember the milk!
----
The AsciiDoc processor will resolve the admonition icon to [.path]_./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:
[source]
----
= Documemnt Title
:icons: image
:iconsdir: icons
----
When converting this document, the AsciiDoc processor will look for images in the [.path]_icons_ directory instead of the default [.path]_./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:
[source]
----
= Documemnt Title
:icons: image
:icontype: svg
----
For NOTE admonitions, the AsciiDoc processor will now look for the image [.path]_note.svg_ in the `iconsdir` instead of [.path]_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.
Asciidoctor can display icons as text, images, or characters selected from an icon font.
== icons attribute syntax
How an icon is displayed is based on the value assigned to the document attribute `icons`.
By default, the document attribute `icons` is not set.
If `icons` isn't set, features that use built-in icons, such as callout numbers and admonition blocks, use their fallback text.
Admonitions are displayed with their label (e.g., CAUTION) and callout numbers are displayed as plain text.
However, Asciidoctor will still process any icon macros and look for icon files in the icons directory (`iconsdir`).
By default, `iconsdir` is set to [.path]_./images/icons/_.
//The icon file extension is set using the `icontype` attribute, which defaults to PNG (`.png`).
When the `icons` attribute is set, its value can be left blank or be `font`.
_empty_:: When `icons` is set and its value field is empty, Asciidoctor looks for icon images in the icons directory (`iconsdir`).
Additionally, the DocBook converter provides built-in images for the admonition and callout icons.
+
[source]
----
= Document Title
:icons:
----
`font`:: When `icons` is set and its value field is assigned `font`, the Asciidoctor HTML converter uses the Font Awesome icon set for admonition labels, callout numbers, and inline symbols.
DocBook does not support font-based icons, so the DocBook output is not affected if the value `font` is assigned to the `icons` attribute.
+
[source]
----
= Document Title
:icons: font
----
When an image or font-based icon isn't available, Asciidoctor displays the icon macro's fallback text.
== Icon macro syntax
An icon can be inserted at an arbitrary place in your content with the icon macro.
[source]
----
icon:file-name[]
----
Enter the file name of the icon in the target field of the icon macro, followed by a set of square brackets (`[]`).
Depending on the value of `icons` and the converter, Asciidoctor will look for the icon file (e.g., [.path]_file-name_) in the icons directory (`iconsdir`) or in the font icon set.
The file extension (e.g., _.png_) doesn't have to be specified as long as it matches the value of the `icontype` attribute.
`icontype` is set to `.png` by default.
You can also assign one or more attributes to an icon.
Attributes are assigned inside the macro's square brackets (`[]`) in a comma-separated list.
The available attributes depend on the value assigned to the `icons` attribute.
////
.Relationship to the inline image macro
--
The inline icon macro is similar to the inline image macro with a few exceptions:
* If the icons attribute has the value font, the macro will translate to a font-based icon in the HTML converter (e.g., `<i class="icon-tags"></i>`)
* If the icons attribute does not have the value font, or the converter is DocBook, the macro will insert an image into the document that resolves to a file in the iconsdir directory (e.g., `<img src="./images/icons/tags.png">`)
The file resolution strategy when using image-based icons is the same used to locate images for the admonition icons.
The file extension is set using the `icontype` attribute, which defaults to PNG (`png`).
Asciidoctor can display icons as text, images, or characters selected from an icon font.
Icons are a useful way to communicate information visually while at the same time eliminating text that can distract from the primary text.
Icons also have the benefit of adding some flair to your document.
In AsciiDoc, there are numerous ways to embellish the output of your document with icons (for backends that support this feature).
== icons attribute syntax
For some elements, icons are added automatically by the processor when enabled, such as the admonition icons.
You can also add icons directly to the content using special markup.
How an icon is displayed is based on the value assigned to the document attribute `icons`.
This section shows you how to enable icons, covers the various icon modes, and introduces you to the icon macro for adding custom icons to your content.
By default, the document attribute `icons` is not set.
If `icons` isn't set, features that use built-in icons, such as callout numbers and admonition blocks, use their fallback text.
Admonitions are displayed with their label (e.g., CAUTION) and callout numbers are displayed as plain text.
However, Asciidoctor will still process any icon macros and look for icon files in the icons directory (`iconsdir`).
By default, `iconsdir` is set to [.path]_./images/icons/_.
//The icon file extension is set using the `icontype` attribute, which defaults to PNG (`.png`).
== Enable icons
When the `icons` attribute is set, its value can be left blank or be `font`.
There are three icon modes: text, image, and font.
_empty_:: When `icons` is set and its value field is empty, Asciidoctor looks for icon images in the icons directory (`iconsdir`).
Additionally, the DocBook converter provides built-in images for the admonition and callout icons.
+
[source]
----
= Document Title
:icons:
----
The inclusion of icons in the output is controlled using the `icons` document attribute.
By default, this attribute is not set.
As a result, all icons are displayed as text.
In the text icon mode, icons are effectively disabled.
`font`:: When `icons` is set and its value field is assigned `font`, the Asciidoctor HTML converter uses the Font Awesome icon set for admonition labels, callout numbers, and inline symbols.
DocBook does not support font-based icons, so the DocBook output is not affected if the value `font` is assigned to the `icons` attribute.
+
[source]
----
= Document Title
:icons: font
----
When an image or font-based icon isn't available, Asciidoctor displays the icon macro's fallback text.
== Icon macro syntax
An icon can be inserted at an arbitrary place in your content with the icon macro.
To enable icons, set the `icons` attribute in the document header.
[source]
----
icon:file-name[]
= Document Title
:icons:
----
Enter the file name of the icon in the target field of the icon macro, followed by a set of square brackets (`[]`).
Depending on the value of `icons` and the converter, Asciidoctor will look for the icon file (e.g., [.path]_file-name_) in the icons directory (`iconsdir`) or in the font icon set.
The file extension (e.g., _.png_) doesn't have to be specified as long as it matches the value of the `icontype` attribute.
`icontype` is set to `.png` by default.
Valid values for the `icons` attribute are as follows:
You can also assign one or more attributes to an icon.
image (or empty)::
Icons resolve to image files in the directory specified by the `iconsdir` attribute.
Icons are loaded from an icon font (like Font Awesome).
Not all backends support this mode, such as DocBook.
Attributes are assigned inside the macro's square brackets (`[]`) in a comma-separated list.
The available attributes depend on the value assigned to the `icons` attribute.
== Where icons are used
////
.Relationship to the inline image macro
--
The inline icon macro is similar to the inline image macro with a few exceptions:
Setting the `icon` attribute turns on icons in the following locations:
* If the icons attribute has the value font, the macro will translate to a font-based icon in the HTML converter (e.g., `<i class="icon-tags"></i>`)
* If the icons attribute does not have the value font, or the converter is DocBook, the macro will insert an image into the document that resolves to a file in the iconsdir directory (e.g., `<img src="./images/icons/tags.png">`)
* The admonition label is replaced with an icon (i.e., admonition icons)
