You can assign one or more roles to blocks and most inline elements using 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.
adds additional semantics to an element
can be used to apply additional styling to a group of elements (e.g., via a CSS class selector)
may activate additional behavior if recognized by the converter
You can assign roles to blocks using the shorthand dot (
.) syntax or the longhand (
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
[.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 (
[.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,
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.
[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.
[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.
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.
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.
<p>This sentence contains <strong class="application">bold inline content</strong> that’s assigned a role.</p> <p>This sentence contains <code class="varname">monospace text</code> that’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.