Attributes allow you 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|https://html.spec.whatwg.org/multipage/dom.html#global-attributes]].

Typical use cases for attributes are to specify the (natural) [[language|00001007050100]] for a text region, to specify the [[programming language|00001007050200]] 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+005F).
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 to 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:

* ''``Hello, world``{-}'' produces ==Hello, world=={-}.
* ''``Hello, world``'' produces ==Hello, world==.

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|00001007030000]], 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|00001007040000]], the attributes must immediately follow the inline markup.

``::GREEN::{example}`` is allowed, but not ``::GREEN:: {example}``.


=== Reference material
* [[Supported attribute values for natural languages|00001007050100]]
* [[Supported attribute values for programming languages|00001007050200]]