Attributes allows to modify the way how material is presented. Alternatively, they provide additional information to markup elements. To some degree, attributes are similar to HTML attributes.
Typical use cases for attributes are to specify the (natural) language for a text region, to specify the programming language for highlighting program code, or to make white space visible in plain text.
Attributes are specified within curly brackets {...}. Of course, more than one attribute can be specified. Attributes are separated by a sequence of space characters or by a comma character.
An attribute normally consists of an optional key and an optional value. The key is a sequence of letters, digits, a hyphen-minus (“-”, U+002D, and a low line / underscore (“_”, U+005D). It can be empty. The value is a sequence of any character, except space and the right curly bracket (“}”, U+007D). If the value must contain a space or the right curly bracket, the value can be specified within two quotation marks (“"”, U+0022). Within the quotation marks, the backslash character functions as an escape character to specify the quotation mark (and the backslash character too).
Some examples:
{key=value} sets the attribute key to value value.{key="value with space"} sets the attribute to the given value.{key="value with quote \" (and backslash \\)"}{name} sets the attribute name. It has no corresponding value. It is equivalent to {name=}.{=key} sets the generic attribute to the given value. It is mostly used for modifying behavior according to a programming language.{.key} sets the class attribute to the given value. It is equivalent to {class=key}.In these examples, key must conform the the syntax of attribute keys, even if it is used as a value.
If a key is given more than once in an attribute, the values are concatenated (and separated by a space).
{key=value1 key=value2} is the same as {key"value1 value2"}.{key key} is the same as {key}.{.class1 .class2} is equivalent to {class="class1 class2"}.This is not true for the generic attribute. In {=key1 =key2}, the first key is ignored. Therefore it is equivalent to {=key2}.
The key “-” (just hyphen-minus) is special. It is called default attribute and has a markup specific meaning. For example, when used for plain text, it replaces the non-visible space with a visible representation:
Attributes may be continued on the next line when a space or line ending character is possible. In case of a quoted attribute value, the line ending character will be part of the attribute value. For example:
{key="quoted
value"}will produce a value quoted\nvalue (where \n denotes a line ending character).
::GREEN::{class=example
background=grey}is allowed, but not
::GREEN::{background=color:
green}However,
::GREEN::{background=color:"
green"}is allowed, because line endings are allowed within quotes.
For block-structured elements, there is a syntax variant if you only want to specify a generic attribute. For all line-range blocks you can specify the generic attributes directly in the first line, after the three (or more) characters starting the block.
:::attr
...
:::is equivalent to
:::{=attr}
...
:::For block-structured elements, spaces are allowed between the blocks characters and the attributes.
=== Heading {example}is allowed and equivalent to
=== Heading{example}For inline-structured elements, the attributes must immediately follow the inline markup.
::GREEN::{example} is allowed, but not ::GREEN:: {example}.