Loading...

May 23, 2014

Awesome Asciidoctor: Substitute Attribute in Listing Block

To write a listing block where the contents of the block is generated in a monospace font and line breaks are preserved is easy with Asciidoc. We can use ---- or [listing] or indent the paragraph with one space to define a listing block. All content in a listing block is processed as is, but special characters and callouts are processed. This means if we have an attribute in our block the attribute is not substituted with the actual value. To enable the replacement of the attribute with the attribute value we must set the subs attribute for our listing block.

Suppose we have the following listing block in our documentation with the attribute grailsVersion in the content:

:grailsVersion: 2.3.8

----
$ grails -version
Grails version: {grailsVersion}
----

When we generate HTML output we get the following result:

We add now the subs attribute to our listing:

:grailsVersion: 2.3.8

[subs="attributes"]
----
$ grails -version
Grails version: {grailsVersion}
----

The generated HTML now shows that the attribute value is used:

Alternative ways to define the listing block with the subs attribute. These will render the same result:

[listing,subs="attributes"]
$ grails -version
Grails version: {grailsVersion}

[subs="attributes"]
 $ grails -version
 Grails version: {grailsVersion}

Written with Asciidoctor 0.1.4.