Role Attribute

You can assign one or more roles to blocks and most inline elements using the role attribute. The role attribute is a named attribute. Even though the attribute name is singular, it may contain multiple (space-separated) roles. Roles may also be defined using a shorthand (dot-prefixed) syntax.

A role:

  1. adds additional semantics to an element

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

  3. may activate additional behavior if recognized 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 synonymous with HTML class names, thus allowing output elements to be identified and styled in CSS using class selectors (e.g., sidebarblock.role1).

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 style style position of 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.
****

The role values are turned into a space-separated list of values, role1 role2.

Formal role syntax for blocks

You can define the roles using a named attribute instead, which is the longhand syntax for adding roles to an element. When using this syntax, add the attribute name role followed by the equals sign (=) then the role name or names to any position in the block 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 using spaces. Since the value has spaces, it’s easier to read if enclosed in quotes, though the quotes are not strictly required.

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 form, the value of the role attribute is already in the right form to be passed through to the output. No additional processing is done on it.

This longhand syntax can also be used on inline macros, but it cannot be used with formatted (aka quoted) text.

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 element in DocBook or DITA.