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

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`

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.