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
47
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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
= Font and Image Icons
:description: Font-based or image icons are enabled with the `icons` document attribute.
Font-based or image icons are enabled with the `icons` document attribute.
== icons attribute
The `icons` document attribute allows you to replace the default text-based labels for admonitions with font-based icons or images.
Setting the `icons` attribute also enables the `icon` macro.
The `icons` attribute accepts the following values:
font:: To use font-based icons for admonitions and with the icon macro, set the `icons` attribute and assign it the value `font`.
See <<font>> for details.
image:: To use local image files, set the `icons` attribute and assign it the value `image`.
While the icon macro is enabled when the value is `image`, it will only produce text-based output.
Alternatively, you can enable the use of fonts during PDF generation by passing the `icons` attribute to the `asciidoctor-pdf` command instead setting it in the document header.
$ asciidoctor-pdf -a icons=font -a icon-set=fas sample.adoc
By setting `icons`, the xref:theme:admonition.adoc#icon-name[theme can control the icon used for each type of admonition].
[#font]
== Activate font-based icons
You can enable font-based icons by setting the `icons` document attribute in the header of your document:
[,asciidoc]
----
:icons: font
----
If you want to override the font set globally, also set the `icon-set` attribute:
[,asciidoc]
----
:icons: font
:icon-set: fas
----
You can use font-based icons from any of the following icon sets in your PDF document:
* *fa* - https://fontawesome.com/v4.7.0/icons (default, deprecated)
* *fas* - https://fontawesome.com/icons?d=gallery&s=solid[Font Awesome - Solid^]
* *fab* - https://fontawesome.com/icons?d=gallery&s=brands[Font Awesome - Brands^]
* *far* - https://fontawesome.com/icons?d=gallery&s=regular[Font Awesome - Regular^]
* *fi* - http://zurb.com/playground/foundation-icon-fonts-3[Foundation Icons^]
* *pf* - Payment font (deprecated)
Use of the fa icon set is deprecated.
Please use one of the styled FontAwesome icon sets.
The pf icon set is no longer maintained.
Prefer the brand icons either from fab or fi instead.
Icon-based fonts are handled by the `prawn-icon` gem.
To find a complete list of available icons, consult the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon^] repository.
[#icon-macro]
== Insert an icon
Here's an example that shows how to use the Android icon from the Foundation Icons (fi) icon set in a sentence (assuming the `icon-set` is set to `fi`):
[,asciidoc]
----
:icons: font
:icon-set: fi
Available for icon:social-android[].
----
You can use the `set` attribute on the icon macro to override the icon set for a given icon.
[,asciidoc]
----
:icons: font
Available for icon:social-android[set=fi].
----
You can also specify the font set using the following shorthand.
[,asciidoc]
----
:icons: font
Available for icon:social-android@fi[].
----
It's a good practice to always specify the icon set in some way.
In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc.), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc.).
[,asciidoc]
----
:icons: font
icon:android[set=fab,size=40em]
----
|
