Role Category Keys

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.

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.
Key Value Type Example

background-color
(i)

Color
(default: not set)

 
role:
  high-contrast:
    background-color: #121212

border-color
(i)

Color
(default: not set)

 
role:
  found:
    border-color: #CCCCCC

border-offset
(i)

Number
(default: 0)

 
role:
  found:
    border-offset: 2

border-radius
(i)

Measurement
(default: not set)

 
role:
  found:
    border-radius: 3

border-width
(i)

Measurement
(default: not set)

 
role:
  found:
    border-width: 0.5

font-color
(i, p)

Color
(default: inherit)

 
role:
  red:
    font-color: #FF0000

font-family
(i, p)

Font family name
(default: inherit)

 
role:
  label:
    font-family: M+ 1mn

font-size
(i, p)

Font size
(default: inherit)

 
role:
  large:
    font-size: 12

font-style
(i, p)

Font style
(default: inherit)

 
role:
  heavy:
    font-style: bold

text-align
(p)

Text alignment
(default: inherit)

 
role:
  declare:
    text-align: center

text-decoration
(i)

Text decoration
(default: none)

 
role:
  deleted:
    text-decoration: line-through

text-decoration-color
(i)

Color
(default: $role-<name>-font-color)

 
role:
  deleted:
    text-decoration-color: #FF0000

text-decoration-width
(i)

Number
(default: $base-text-decoration-width)

 
role:
  underline:
    text-decoration-width: 0.5

text-transform
(i, p)

Text transform
(default: inherit)

 
role:
  heavy:
    text-transform: uppercase

To learn more about defining a custom role, see Custom Roles.

Built-in roles

Asciidoctor PDF provides several predefined roles. You can 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.

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.

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.

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.

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 custom roles in your theme if you’d like to make use of them when converting to PDF.