Attribute Entry Names and Values

Valid built-in names

Built-in attribute names are reserved and can’t be re-purposed for user-defined attribute names. The built-in attribute names are listed in the Document Attributes Reference and Character Replacement Attributes Reference.

Valid user-defined names

User-defined attribute names must:

  • be at least one character long,

  • begin with a word character (a-z, 0-9, or _), and

  • only contain word characters and hyphens (-).

A user-defined attribute name cannot contain dots (.) or spaces. Although uppercase characters are permitted in an attribute name, the name is converted to lowercase before being stored. For example, URL-REPO and URL-Repo are treated as url-repo when a document is loaded or converted. A best practice is to only use lowercase letters in the name and avoid starting the name with a number.

Attribute value types and assignment methods

Depending on the attribute, its value may be an empty string, an integer such as 5 or 2, or a string of characters like your name or a URL. Attributes that accept string values may include references to other attributes and inline macros. Values can’t contain complex, multi-line block elements such as tables or sidebars.

An attribute’s value may be assigned by default when the value is left empty in an attribute entry or the value may be assigned explicitly by the user. The type of value an attribute accepts and whether it uses a default value, has multiple built-in values, accepts a user-defined value, or requires a value to be explicitly assigned depends on the attribute.

Built-in values

Many built-in attributes have one or more built-in values. One of these values may be designated as the attribute’s default value. The AsciiDoc processor will fall back to this default value if you set the attribute but leave the value empty. Additionally, the processor automatically sets numerous built-in attributes at processing time and assigns them their default values unless you explicitly unset the attribute or assign it another value. For instance, the processor automatically sets all of the character replacement attributes.

If you want to use the non-default value of a built-in attribute, you need to set it and assign it an alternative value.

Empty string values

The value for built-in boolean attributes is always left empty in an attribute entry since these attributes only turn on or turn off a feature. During processing, the AsciiDoc processor assigns any activated boolean attributes an empty string value.

Explicit values

You must explicitly assign a value to an attribute when:

  • it doesn’t have a default value,

  • you want to override the default value, or

  • it’s a user-defined attribute.

The type of explicit value a built-in attribute accepts depends on the attribute. User-defined attributes accept string values. Long explicit values can be wrapped.