There are two kinds of elements in AsciiDoc, block elements and inline elements.
[#block-element]
== Block elements
A [.term]*block element* is stacked vertically (by line) above or below other block elements.
Block elements are typically referred to simply as [.term]*blocks*.
Examples of blocks include sections, paragraphs, lists delimited blocks, tables, and block macros.
Blocks are easy to identify because they're usually separated from other blocks by a blank line (though not always required).
Some blocks, such as sections and delimited blocks, can nest other blocks inside of them.
Every block can have one or more lines of block metadata.
This metadata can be in the form of block attributes, a block anchor, or a block title.
These metadata lines should be directly adjacent to the block itself.
[#inline-element]
== Inline elements
An [.term]*inline element* performs an operation on a span of content within a <<block-element,block element>>.
Inline elements include inline macros such as the icon macro (`icon:[]`) and xref macro (`<< >>`, `xref:[]`), attribute references, and text marked up by inline formatting (italic, bold, etc.).
You can see the available icons and their names on the {url-fontawesome-icons}[Font Awesome icons page^].
Using the Font Awesome icons requires online access by default.
IMPORTANT: The default CSS stylesheet is required when using font-based icons.
== Use the Font Awesome icons
To use Font Awesome's icons in your document, set the value of the `icons` document attribute to `font` in the document header.
[source]
----
= Document Title
:icons: font <.>
icon:tags[] ruby, asciidoctor <.>
----
<.> Set `icons` to `font` to use the Font Awesome icons.
<.> Enter the name of the Font Awesome icon in the target field of the inline icon macro, followed by a pair of square brackets (`[]`).
.Result: Use Font Awesome tags icon
icon:tags[] ruby, asciidoctor
When font-based icons are activated, Asciidoctor adds a reference to the Font Awesome stylesheet and font files served from a CDN to the document header:
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:
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 pair 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`).
