Reference Document Attributes

You’ll likely want to insert the value of a user-defined or built-in document attribute in various locations throughout a document. To reference a document attribute for insertion, enclose the attribute’s name in curly brackets (e.g., {name-of-attribute}). This inline element is called an attribute reference. The AsciiDoc processor replaces the attribute reference with the value of the attribute. To prevent this replacement, you can prefix the element with a backslash (e.g., \{name-of-attribute}).

Reference a custom attribute

Before you can reference a custom (i.e., user-defined) attribute in a document, it must first be declared using an attribute entry in the document header. In Example 1, we declare two user-defined attributes that we’ll later be able to reference.

Example 1. Custom attributes set in the document header
= Ops Manual
: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

Once you’ve set and assigned a value to a document attribute, you can reference that attribute throughout your document. In Example 2, the attribute url-repo is referenced twice and disclaimer is referenced once.

Example 2. Custom attributes referenced in the document body
Asciidoctor is {url-repo}[open source]. (1)

WARNING: {disclaimer} (2)
If you're missing a lime colored sock, file a ticket in
the {url-repo}/issues[Asciidoctor issue tracker]. (3)
(Actually, please don't).
1 Attribute references can be used in macros.
2 Attribute references can be used in blocks, such as admonitions, and inline. 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.
3 The reference to the url-repo attribute is inserted to build the complete URL address, which is interpreted as a URL macro.

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

Asciidoctor is open source.

Don’t pet the wild Wolpertingers. We’re not responsible for any loss of hair, chocolate, or purple socks. If you’re missing a lime colored sock, file a ticket in the Asciidoctor issue tracker. Actually, please don’t.

Reference a built-in attribute

A built-in document attribute (i.e., a document attribute which is automatically set by the processor) is referenced the same way as a custom (i.e., user-defined) document attribute. For instance, an AsciiDoc processor automatically sets these supported character replacement attributes. That means that you can reference them throughout your document without having to create an attribute entry in its header.

TIP: Wolpertingers don't like temperatures above 100{deg}C. (1)
Our servers don't like them either.
1 Reference the character replacement attribute deg by enclosing its name in a pair of curly brackets ({ and }).

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

Wolpertingers don’t like temperatures above 100°C. Our servers don’t like them either.

Escape an attribute reference

You may have a situation where a sequence of characters occurs in your content that matches the syntax of an AsciiDoc attribute reference, but is not, in fact, an AsciiDoc attribute reference. For example, if you’re documenting path templating, you may need to reference a replaceable section of a URL path, which is also enclosed in curly braces (e.g., /items/{id}). In this case, you need a way to escape the attribute reference so the AsciiDoc processor knows to skip over it. Otherwise, the processor could warn about a missing attribute reference or perform an unexpected replacement. AsciiDoc provides several ways to escape an attribute reference.

Prefix with a backslash

You can escape an attribute reference by prefixing it with a backslash. When the processor encounters this syntax, it will remove the backslash and pass through the remainder of what looks to be an attribute reference as written.

In Example 3, the attribute reference is escaped using a backslash.

Example 3. An attribute reference escaped using a backslash
In the path /items/\{id}, id is a path parameter.

In the output of Example 3, we can see that the {id} expression in the path is preserved.

In the path /items/{id}, id is a path parameter.

Keep in mind that the backslash will only be recognized if the text between the curly braces is a valid attribute name. If the syntax that follows the backslash does not match an attribute reference, the backslash will not be removed during processing.

Enclose in a passthrough

You can also escape an attribute reference by enclosing it in an inline passthrough. In this case, the processor uses the normal substitution rules for the passthrough type you have chosen.

In Example 4, the attribute reference is escaped by enclosing it in an inline passthrough.

Example 4. An attribute reference escaped by enclosing it in an inline passthrough
In the path +/items/{id}+, id is a path parameter.

In the output of Example 4, we can see that the {id} expression in the path is preserved.

In the path /items/{id}, id is a path parameter.

When using an inline passthrough, you don’t have to worry whether the curly braces form an attribute reference or not. All the text between the passthrough enclosure will get passed through to the output.

Alternative escape mechanisms

Attribute references are replaced by the attributes substitution. Therefore, wherever you can control substitutions, you can prevent attribute references from being replaced. This includes the inline pass macro as well as the subs attribute on a block. See using passthroughs to prevent substitutions for more details.