You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

55 lines
1.7 KiB

4 years ago
////
Included in:
- user-manual: Using attributes: set, assign, and reference
////
Before you can use an attribute in your document, it must be set.
(Sometimes referred to as "`toggling on`" the attribute).
Some attributes are automatically set when {adr} processes a document.
You can also set (or override) an attribute for a document by declaring an attribute entry.
For example:
:sectnums:
Many attributes can be assigned a value at the same time:
:leveloffset: 3
The value may be empty, a string (of characters) or a number.
A string value may include references to other attributes.
Attributes can be unset using the bang symbol (`!`).
The `!` can be placed either before or after the attribute's name.
For example, both:
:sectnums!:
and
:!sectnums:
mean unset the `sectnums` attribute.
In this case, it tells Asciidoctor to not number the sections.
To soft unset an attribute from the CLI or API, you can use the following syntax:
!name=@
The leading `!` unsets the attribute while the `@` lowers the precedence of the assignment.
This assignment is almost always used to unset a default value while still allowing the document to assign a new one.
One such example is `sectids`, which is enabled by default.
`!sectids=@` switches the setting off.
An [.term]_attribute reference_ is an inline element composed of the name of the attribute enclosed in curly brackets.
For example:
The value of leveloffset is {leveloffset}.
The attribute reference is replaced by the attribute's value when Asciidoctor processes the document.
Referencing an attribute that is not set is considered an error and is handled specially by the processor.
The following sections will show you how to use attributes on your whole document, individual blocks, and inline elements.