= Roles
:description: Assign built-in and custom roles to paragraphs and inline phrases.

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.

[#built-in]
== 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.

include::theme:page$role.adoc[tag=user-formatting]

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

[,asciidoc]
----
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.

include::theme:page$role.adoc[tag=para-roles]

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

[,asciidoc]
----
[.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.

[#custom]
== 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.

NOTE: 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,built-in roles>>, such as `lead`, can be augmented or redefined in the same way.

IMPORTANT: Before you can use a custom role in your document, you need to define it in your theme.
See xref:theme:custom-role.adoc[] and xref:theme:role.adoc[] to learn how to create a custom role.

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

[,yaml]
----
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.

[,asciidoc]
----
== 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.
----