Catch a Missing or Undefined Attribute

By default, the original AsciiDoc processor drops the entire line if it contains a reference to a missing attribute (e.g., {bogus}). This "feature" was added for use in templates written for the original processor, which also used the AsciiDoc syntax.

This behavior is not needed in Asciidoctor since templates are written in a dedicated template language (e.g., ERB, Haml, Slim, etc.). More critically, the behavior is frustrating for the author, editor or reader. To them, it’s not immediately apparent when a line goes missing. Discovering its absence often requires a full (and tedious) read-through of the document or section.

Asciidoctor has two attributes to alleviate this inconvenience: attribute-missing and attribute-undefined.

Missing attribute

The attribute attribute-missing controls how missing references are handled. By default, missing references are left intact so it’s clear to the author when one hasn’t been satisfied since, likely, the intent is for it to be replaced.

This attribute has four possible values:

skip

leave the reference in place (default setting)

drop

drop the reference, but not the line

drop-line

drop the line on which the reference occurs (compliant behavior)

warn

print a warning about the missing attribute

Consider the following line of AsciiDoc:

Hello, {name}!

Here’s how the line is handled in each case, assuming the name attribute is not defined:

skip

Hello, {name}!

drop

Hello, !

drop-line

warn
 WARNING: skipping reference to missing attribute: XYZ

Undefined attribute

The attribute attribute-undefined controls how expressions that undefine an attribute are handled. By default, the line is dropped since the expression is a statement, not content.

This attribute has two possible values:

drop

substitute the expression with an empty string after processing it

drop-line

drop the line that contains this expression (default setting and compliant behavior)

The option skip doesn’t make sense here since the statement is not intended to produce content.

Consider the following declaration:

{set:name!}

Depending on whether attribute-undefined is drop or drop-line, either the statement or the line that contains it will be discarded. It’s reasonable to stick with the compliant behavior, drop-line, in this case.

We recommend putting any statement that undefines an attribute on a line by itself.