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)