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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
= Role Category Keys
:description: Asciidoctor PDF provides built-in roles and the ability to define custom roles that can be applied to paragraphs and inline phrases.
:navtitle: Role
:source-language: yaml
[#role]
== role
The keys in the `role` category define custom roles for formatting.
The name of the role is the subkey.
The keys under the role are the theming properties.
The role name may contain a hyphen, but *a role name cannot contain an underscore*.
IMPORTANT: Custom roles only apply to paragraphs and inline phrases (text).
In the table below, the *p* indicates keys which are recognized when the role is applied to a paragraph and the *i* indicates keys which are recognized when the role is applied to an inline phrase.
[cols="3,4,5a"]
|===
|Key |Value Type |Example
|background-color +
(i)
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
role:
high-contrast:
background-color: #121212
|border-color +
(i)
|xref:color.adoc[Color] +
(default: _not set_)
|[source]
role:
found:
border-color: #CCCCCC
|border-offset +
(i)
|xref:language.adoc#values[Number] +
(default: `0`)
|[source]
role:
found:
border-offset: 2
|border-radius +
(i)
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
role:
found:
border-radius: 3
|border-width +
(i)
|xref:measurement-units.adoc[Measurement] +
(default: _not set_)
|[source]
role:
found:
border-width: 0.5
|font-color +
(i, p)
|xref:color.adoc[Color] +
(default: _inherit_)
|[source]
role:
red:
font-color: #FF0000
|font-family +
(i, p)
|xref:font-support.adoc[Font family name] +
(default: _inherit_)
|[source]
role:
label:
font-family: M+ 1mn
|font-size +
(i, p)
|xref:text.adoc#font-size[Font size] +
(default: _inherit_)
|[source]
role:
large:
font-size: 12
|font-style +
(i, p)
|xref:text.adoc#font-style[Font style] +
(default: _inherit_)
|[source]
role:
heavy:
font-style: bold
|text-align +
(p)
|xref:text.adoc#text-align[Text alignment] +
(default: _inherit_)
|[source]
role:
declare:
text-align: center
|text-decoration +
(i)
|xref:text.adoc#decoration[Text decoration] +
(default: `none`)
|[source]
role:
deleted:
text-decoration: line-through
|text-decoration-color +
(i)
|xref:color.adoc[Color] +
(default: `$role-<name>-font-color`)
|[source]
role:
deleted:
text-decoration-color: #FF0000
|text-decoration-width +
(i)
|xref:language.adoc#values[Number] +
(default: `$base-text-decoration-width`)
|[source]
role:
underline:
text-decoration-width: 0.5
|text-transform +
(i, p)
|xref:text.adoc#transform[Text transform] +
(default: _inherit_)
|[source]
role:
heavy:
text-transform: uppercase
|===
To learn more about defining a custom role, see xref:custom-role.adoc[].
[#built-in]
== Built-in roles
Asciidoctor PDF provides several predefined roles.
You can xref:ROOT:roles.adoc[use these roles] when using a built-in theme or a custom theme that extends a built-in theme.
You can also redefine the built-in roles in your theme configuration file.
// tag::user-formatting[]
lead:: The `lead` role defines the font properties for a lead paragraph or phrase.
The built-in themes configure this role to set the font size to the `$base-font-size-large` value.
This role is automatically assigned to the first paragraph of the preamble if a role is not already declared.
big:: The `big` role maps the font size to the `$base-font-size-large` value.
small:: The `small` role maps the font size to the `$base-font-size-small` value.
underline:: The `underline` role adds the underline decoration.
line-through:: The `line-through` role adds the strikethrough decoration.
subtitle:: The `subtitle` role is used to configure the font properties of the subtitle of a section title.
// end::user-formatting[]
// tag::para-roles[]
text-justify:: Aligns the text to the left margin with justification.
text-left:: Aligns the text to the left margin (without justification).
text-right:: Aligns the text to the right margin.
text-center:: Aligns the text to the center of the page.
// end::para-roles[]
unresolved:: The `unresolved` role is applied automatically to the text of an unresolved footnote reference.
(Only recognizes the `font-color` theme key).
noborder:: Only applies to block images.
If this role is present on the block image, the border will not be drawn even if configured on the `image` category in the theme.
This role cannot be redefined.
NOTE: The color roles (e.g., `blue`), which you may be familiar with from the HTML converter, are not mapped by default.
You'll need to define these color roles as xref:custom-role.adoc[custom roles] in your theme if you'd like to make use of them when converting to PDF.
|
