attribute-entries.adoc 3.78 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
= Attribute Entries

== What is an attribute entry?

Before you can use a document attribute in your document, you have to declare it.
An [.term]*attribute entry* is the primary mechanism for defining a document attribute in an AsciiDoc document.
You can think of an attribute entry as a global variable assignment for AsciiDoc.
The document attribute it creates becomes available from that point forward in the document.
Attribute entries are also frequently used to toggle features.

An attribute entry consists of two parts: an attribute *name* and an attribute *value*.
The attribute name comes first, followed by the optional value.
Each attribute entry must be entered on its own line.
An attribute entry starts with an opening colon (`:`), directly followed by the attribute's name, and then a closing colon (`:`).
This [.term]*sets* -- that is, turns on -- the document attribute so you can use it in your document.

[source]
----
:name-of-an-attribute: <.>
----
<.> The attribute's name is directly preceded with a opening colon (`:`) and directly followed by a closing colon (`:`).

In many cases, you explicitly assign a value to a document attribute by entering information after its name in the attribute entry.
The value must be offset from the closing colon (`:`) by at least one space.
Be aware that xref:attribute-entry-substitutions.adoc[header substitutions] automatically get applied to the value by default.

[source]
----
:name-of-an-attribute: value of the attribute <.>
----
<.> An explicitly assigned value is offset from the closing colon (`:`) by at least one blank space.
At the end of the value, press kbd:[Enter].

Some built-in attributes don't require a value to be explicitly assigned in an attribute entry because they're a boolean attribute or have a default value.

[source]
----
:name-of-an-attribute: <.>
----
<.> If you don't want to explicitly assign a value to the attribute, press kbd:[Enter] after the closing colon (`:`).

The values of built-in boolean attributes are always blank because their only accepted value is an _empty string_.
Other built-in attributes may have a default value.
If you set a built-in attribute and leave its value blank, Asciidoctor assigns the default value, if it has one, to the attribute at processing time.

== Where can I use an attribute entry?

An attribute entry is typically defined in the document header.
Dan Allen's avatar
Dan Allen committed
49
When set in the document header, the attribute is available to the entire document until it is reset or unset.
50
51
52
53
The attribute's value can be reassigned or the attribute unset at any subsequent point in the document, unless the attribute is locked (typically by defining it using the CLI or API).

Many, but not all, document attributes can be set, assigned a value, or unset in the document's body (anywhere below the document header).
When you set an attribute in the body, it's visible from the point it's set until it's unset.
54
See the xref:document-attributes-reference.adoc[] for where in a document each attribute can be set.
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

Finally, document attributes can also be set, assigned values, and unset via the CLI and API, but these methods don't use the attribute entry syntax.
When an attribute is set from the command line or API, it's defined for the whole document and can't be changed in the document header or body unless `@` is added to the end of the value.
See xref:assignment-precedence.adoc[] for more information.
The one exception to this rule is the `sectnums` attribute, which can always be changed.

////
An exclamation point (`!`) before (or after) the attribute name unsets the attribute.

[source]
----
:!name: <1>
----
<1> The leading `!` indicates this attribute should be unset.
In this case, the value is ignored.

An attribute entry must start at the beginning of the line.
If the attribute entry follows a paragraph, it must be offset by a blank line.
////