reference-attributes.adoc 3.11 KB
Newer Older
1
2
= Reference Document Attributes
:navtitle: Reference Attributes
3
4
5
6
7
8
9
10
:disclaimer: Don't pet the wild Wolpertingers. We're not responsible for any loss \
of hair, chocolate, or purple socks.
:url-repo: https://github.com/asciidoctor/asciidoctor

You'll likely use the value of a user-defined attribute entry or certain built-in attributes in specific locations throughout a document.
To reference and use the value of a document attribute, you enclose the attribute's name in curly brackets (`+{name-of-an-attribute}+`).
This inline element is called an *attribute reference*.

11
12
[#reference-custom]
== Reference custom attributes
13

14
Before you can reference an attribute in a document it must be declared using an attribute entry in the document header.
15
Let's reference the two user-defined attributes set and assigned values in <<ex-set-custom>>.
16

17
.Custom attributes set in the document header
18
[source#ex-set-custom,subs=+attributes]
19
20
----
= Ops Manual
21
22
:disclaimer: {disclaimer}
:url-repo: {url-repo}
23
24
25
26
27
----

Once you've set and assigned a value to the attribute, you can reference that attribute throughout your document.
In <<ex-reference>>, the attribute `url-repo` is referenced twice and `disclaimer` is referenced once.

28
.Custom attributes referenced in the document body
29
30
31
32
33
34
35
36
37
[source#ex-reference]
----
Asciidoctor is {url-repo}[open source]. <.>

WARNING: {disclaimer} <.>
If you're missing a lime colored sock, file a ticket in
the {url-repo}/issues[Asciidoctor issue tracker]. <.>
----
<.> Attribute references can be used in macros.
38
<.> Attribute references can be used in blocks, such as xref:blocks:admonitions.adoc[admonitions], and inline.
39
Since there isn't a blank line between the `disclaimer` reference and the next sentence, the sentence will be directly appended to the end of the attribute's value when it's processed.
40
<.> The reference to the `url-repo-ex` attribute is inserted into a longer URL address and used in a xref:macros:url-macro.adoc[URL macro].
41
42
43
44
45
46
47
48
49
50

As you can see below, the attribute references are replaced with the corresponding attribute value when the document is processed.

====
Asciidoctor is {url-repo}[open source].

WARNING: {disclaimer}
If you're missing a lime colored sock, file a ticket in the {url-repo}/issues[Asciidoctor issue tracker].
====

51
52
[#reference-built-in]
== Reference an automatically declared attribute
53

54
An automatically set document attribute is referenced the same way as an explicitly set document attribute.
55
For instance, an AsciiDoc processor automatically sets these supported xref:character-replacement-reference.adoc[character replacement attributes].
56
That means that you can reference them throughout your document without having to create an attribute entry in its header.
57
58
59

[source]
----
60
61
TIP: Wolpertingers don't like temperatures above 100{deg}C. <.>
Our servers don't like them either.
62
----
63
<.> Reference the character replacement attribute `deg` by enclosing its name in a pair of curly brackets (`+{ }+`).
64

65
As you can see below, the attribute reference is replaced with the attribute's value when the document is processed.
66

67
68
TIP: Wolpertingers don't like temperatures above 100{deg}C.
Our servers don't like them either.