Role Category Keys

role

The keys in the role category define custom roles for formatting. The name of the role is the first subkey level. The role name may contain a hyphen, but a role name cannot contain an underscore. The keys under the role are the theming properties.

Custom roles only apply to paragraphs and inline phrases.
Key Value Type Example

background-color

Color
(default: not set)

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

border-color

Color
(default: not set)

role:
  found:
    border-color: #CCCCCC

border-offset

Number
(default: 0)

role:
  found:
    border-offset: 2

border-radius

Measurement
(default: not set)

role:
  found:
    border-radius: 3

border-width

Measurement
(default: not set)

role:
  found:
    border-width: 0.5

font-color

Color
(default: inherit)

role:
  red:
    font-color: #FF0000

font-family

Font family name
(default: inherit)

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

font-size

Number
(default: inherit)

role:
  large:
    font-size: 12

font-style

Font style
(default: inherit)

role:
  heavy:
    font-style: bold

text-align

Text alignment
(default: inherit)

role:
  declare:
    text-align: center

text-decoration

Text decoration
(default: none)

role:
  deleted:
    text-decoration: line-through

text-decoration-color

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

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

text-decoration-width

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

role:
  underline:
    text-decoration-width: 0.5

text-transform

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. The lead role is automatically assigned to the first paragraph of the preamble if a role is not already declared. The built-in themes configure this role to set the font size to the $base-font-size-large value.

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.

unresolved

The unresolved role is applied automatically to the text of an unresolved footnote reference.

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.