February 25, 2015

Awesome Asciidoctor: Customize How Missing Attributes Are Handled

Document attributes are like variables for your Asciidoctor document. Normally when we reference an attribute that is not set in our Asciidoctor markup the reference is still in the output. This is very handy, because we immediately see that a document attribute is not set. But we can customize this behavior with the document attribute attribute-missing. We can use the default value skip, which leaves the reference in the output. Another option is drop, which means the reference is dropped from the output. Finally we can set the value to drop-line, where the complete line with the attribute reference is dropped from the output.

In the following sample Asciidoctor markup we set the three values for the attribute attribute-missing:

== Handle Missing Attributes

:attribute-missing: skip

.`:attribute-missing: skip`
Line with attribute {sample-attr}, should show attribute reference.

:attribute-missing: drop

.`:attribute-missing: drop`
Line with attribute {sample-attr}, drops attribute reference.

:attribute-missing: drop-line

.`:attribute-missing: drop-line`
Line with attribute {sample-attr}, is completely dropped.

When we transform this to HTML5 we get the following output:

Written with Asciidoctor 1.5.2.