Chapter 28. Attribute Entries

The AttributeEntry block element allows document attributes to be assigned within an AsciiDoc document. Attribute entries are added to the global document attributes dictionary. The attribute name/value syntax is a single line like:

:<name>: <value>

For example:

:Author Initials: JB

This will set an attribute reference {authorinitials} to the value JB in the current document.

To delete (undefine) an attribute use the following syntax:

:<name>!:

AttributeEntry behavior

The attribute entry line begins with colon — no white space allowed in left margin.
AsciiDoc converts the <name> to a legal attribute name (lower case, alphanumeric, dash and underscore characters only — all other characters deleted). This allows more human friendly text to be used.
Leading and trailing white space is stripped from the <value>.

Lines ending in a space followed by a plus character are continued to the next line, for example:

:description: AsciiDoc is a text document format for writing notes, +
              documentation, articles, books, slideshows, web pages +
              and man pages.

If the <value> is blank then the corresponding attribute value is set to an empty string.
Attribute references contained in the entry <value> will be expanded.
By default AttributeEntry values are substituted for specialcharacters and attributes (see above), if you want to change or disable AttributeEntry substitution use the pass:[] inline macro syntax.
Attribute entries in the document Header are available for header markup template substitution.
Attribute elements override configuration file and intrinsic attributes but do not override command-line attributes.

Here are some more attribute entry examples:

AsciiDoc User Manual
====================
:author:    Stuart Rackham
:email:     srackham@gmail.com
:revdate:   April 23, 2004
:revnumber: 5.1.1

Which creates these attributes:

{author}, {firstname}, {lastname}, {authorinitials}, {email},
{revdate}, {revnumber}

The previous example is equivalent to this document header:

AsciiDoc User Manual
====================
Stuart Rackham <srackham@gmail.com>
5.1.1, April 23, 2004

28.1. Setting configuration entries

A variant of the Attribute Entry syntax allows configuration file section entries and markup template sections to be set from within an AsciiDoc document:

:<section_name>.[<entry_name>]: <entry_value>

Where <section_name> is the configuration section name, <entry_name> is the name of the entry and <entry_value> is the optional entry value. This example sets the default labeled list style to horizontal:

:listdef-labeled.style: horizontal

It is exactly equivalent to a configuration file containing:

[listdef-labeled]
style=horizontal

If the <entry_name> is omitted then the entire section is substituted with the <entry_value>. This feature should only be used to set markup template sections. The following example sets the xref2 inline macro markup template:
```
:xref2-inlinemacro.: <a href="#{1}">{2?{2}}</a>
```
No substitution is performed on configuration file attribute entries and they cannot be undefined.
This feature can only be used in attribute entries — configuration attributes cannot be set using the asciidoc(1) command --attribute option.

Attribute entries promote clarity and eliminate repetition

URLs and file names in AsciiDoc macros are often quite long — they break paragraph flow and readability suffers. The problem is compounded by redundancy if the same name is used repeatedly. Attribute entries can be used to make your documents easier to read and write, here are some examples:

:1:         http://freshmeat.sourceforge.net/projects/asciidoc/
:homepage:  https://asciidoc.org[AsciiDoc home page]
:new:       image:./images/smallnew.png[]
:footnote1: footnote:[A meaningless latin term]

Using previously defined attributes: See the {1}[Freshmeat summary]
or the {homepage} for something new {new}. Lorem ispum {footnote1}.

Note

The attribute entry definition must precede it’s usage.
You are not limited to URLs or file names, entire macro calls or arbitrary lines of text can be abbreviated.
Shared attributes entries could be grouped into a separate file and included in multiple documents.