icons.adoc 3.21 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
= Icons and the Icon Macro

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[]
----

47
Enter the file name of the icon in the target field of the icon macro, followed by a pair of square brackets (`[]`).
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
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.

[source]
----
icon:file-name[optional-attribute=value, optional-attribute=value]
----

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`).
--
////