Role Attribute

You can assign one or more roles to blocks and most inline elements using the role attribute. Even though the attribute is singular, it may contain multiple roles. The role attribute is a named attribute.

A role:

  1. adds additional semantics to an element

  2. can be used for adding additional styling to a group of elements (e.g., via a CSS class selector)

  3. may activate additional behavior if supported by the converter

The role attribute in AsciiDoc always get mapped to the class attribute in the HTML output. In other words, role names are HTML class names, and thus can be targeted using CSS class selectors.

Assign roles to blocks

You can assign roles to blocks using the shorthand dot (.) syntax or the longhand (role=) syntax.

Shorthand role syntax for blocks

To assign a role to a block, prefix the value with a dot (.) in an attribute list. The dot implicitly sets the role attribute.

Example 1. Sidebar block with a role assigned using the shorthand dot
[.rolename]
****
This is a sidebar with a role assigned to it, rolename.
****

You can assign multiple roles to a block by prefixing each value with a dot (.).

Example 2. Sidebar with two roles assigned using the shorthand dot
[.role1.role2]
****
This is a sidebar with two roles assigned to it, role1 and role2.
****

In this case, the value of the role attribute becomes a space separated list of values, role1 role2.

Formal role syntax for blocks

Explicitly set role, followed by the equals sign (=), and then the value in an attribute list.

Example 3. Sidebar block with a role assigned using the formal syntax
[role=rolename]
****
This is a sidebar with one role assigned to it, rolename.
****

Separate multiple role values with commas (,). Since the value contains a comma, the value must be enclosed in quotes.

Example 4. Sidebar with two roles assigned using the formal syntax
[role="role1,role2"]
****
This is a sidebar with two roles assigned to it, role1 and role2.
****

In this case, the value of the role attribute becomes a space separated list of values, role1 role2.

Assign roles to formatted inline elements

You can assign roles to inline elements that are enclosed in formatting syntax, such as bold (*), italic (_), and monospace (`). To assign a role to an inline element that’s enclosed in formatting syntax block, prefix the value with a dot (.) in an attribute list.

Example 5. Inline role assignments using shorthand syntax
This sentence contains [.application]*bold inline content* that's assigned a role.

This sentence contains [.varname]`monospace text` that's assigned a role.

The HTML source code that is output from Example 5 is shown below.

Example 6. HTML source code produced by Example 5
<p>This sentence contains <strong class="application">bold inline content</strong> that&#8217;s assigned a role.</p>

<p>This sentence contains <code class="varname">monospace text</code> that&#8217;s assigned a role.</p>
</div>

As you can see from this output, roles in AsciiDoc are translated to CSS class names in HTML. Thus, roles are an ideal way to annotated elements in your document so you can use CSS to uniquely style them.

The role is often used on a phrase to represent semantics you might have expressed using a dedicated tag in DocBook or DITA.