Roles

You can apply the built-in roles that Asciidoctor PDF supports as well as custom roles you define in your theme. Built-in roles are not supported universally, but rather on specific elements. Custom roles are limited to paragraphs and inline phrases.

Use a built-in role

Asciidoctor PDF supports a subset of the built-in roles defined in AsciiDoc. Where these built-in roles can be applied is limited. If a built-in role is not listed in this section, then you can expect that it’s not supported.

On text

The following built-in roles can be assigned to paragraphs and inline phrases.

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.

In the example below, the built-in role big is applied to an inline phrase.

The sign spelled out [.big]#WELCOME# in glowing neon lights.

When text is enclosed in a pair of single or double hash symbols (#) and has at least one role, the role or roles will be applied to the text without any other implicit formatting. That is, the text will appear with custom styling rather than being displayed as marked (i.e., highlighted) text.

The following built-in roles can be assigned to paragraphs, list items, and discrete headings.

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.

In the example below, the built-in role text-right is applied to a paragraph so it aligns to the right.

[.text-right]
A response is often shown right-aligned like this.

On block images

The following built-in roles can be assigned to block images.

left: Aligns the image to the left margin. Analogous to align=left.
right: Aligns the image to the right margin. Analogous to align=right.
center: Aligns the image to the middle of the page. Analogous to align=center.
noborder: The border will not be drawn even if configured on the image category in the theme.

The purpose of the built-in roles on block images cannot be redefined.

Use a custom role

In AsciiDoc, you can add any role name to an element that supports roles. However, in order for that role to have any effect, you must assign styles to it in a theme.

In Asciidoctor PDF, the theme properties mapped to custom roles currently only apply to paragraphs and inline phrases.

You can define additional roles in your theme using the role category. In addition to custom roles, the built-in roles, such as lead, can be augmented or redefined in the same way.

Before you can use a custom role in your document, you need to define it in your theme. See Custom Roles and Role Category Keys to learn how to create a custom role.

Let’s assume you’ve defined a custom role named labeled in your theme.

role:
  labeled:
    font-color: #0000FF

Now, you can use this role in your documents. In the following example, the custom role is assigned to the second paragraph and an inline phrase in the last paragraph.

== Section title

A paragraph.

[.labeled]
A paragraph styled according to the custom role assigned to it.

Another paragraph.
The text [.labeled]#label me# is formatted using the styles of the custom role.