blob: ecf16629e01eeeac699afa178ae15801cc88703b (
plain) (
blame)
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
|
= Custom Roles
:description: Define custom roles in the PDF theme configuration file to apply special formatting to paragraphs and inline phrases.
Use the keys in the `role` category to define custom roles or redefine the built-in roles.
Custom roles only apply to paragraphs and inline phrases.
== Define a custom role
Custom roles are defined under the `role` category key.
The name of a custom role may contain a hyphen, but *a role name cannot contain an underscore*.
[,yaml]
----
role: <.>
rolename: <.>
font-color: #FF7F50 <.>
font-style: bold
text-decoration: underline
another-role: <.>
border-width: 0.5
----
<.> Custom roles are defined under the `role` category key.
<.> Create a name for your custom role.
<.> Enter a formatting key and its value on a new line under the name of the role.
Each key that you want applied to a role should be entered on a new line.
<.> You can define more than one custom role under the `role` category key.
Role names can contain hyphens, but not underscores.
The formatting keys that a custom role can accept are listed in xref:role.adoc[].
Be aware that some keys do not apply to the context where the role is used.
Let's look at some custom role definition and usage examples in the next section.
== Custom role examples
In the following example, a custom role named `red` is defined.
The keys `background-color` and `font-color` are set and each key is assigned a color value using the xref:color.adoc#hex[hex format].
[,yaml]
----
role:
red:
background-color: #333333
font-color: #FF0000
----
You can also use a custom role to unset the default styling of a paragraph or inline phrase and make it inherit the styling of its parent element.
In the example below, a custom role named `heading-code` is defined and the `font-color` key is unset by assigning a tilde (`~`) as its value.
[,yaml]
----
role:
heading-code:
font-color: ~
----
In the next example, the `red` and `heading-code` custom roles are assigned to text in a document.
[,asciidoc]
----
= Document Title
== Section title
[.red] <.>
Error text is shown in red.
=== [.heading-code]`SELECT` clause <.>
A paragraph.
----
<.> The `red` custom role is assigned to a paragraph.
<.> The `heading-code` custom role is assigned to an inline phrase marked up with the codespan syntax.
The code phrase will inherit the font color of the section heading, because the `heading-code` role unsets the font color that would usually be applied to a code phrase.
However, the phrase `Select` will inherit all the other code phrase styles.
See xref:role.adoc[] for the list of keys a custom role can accept.
|
