Loading...

April 30, 2014

Awesome Asciidoctor: Include Partial Parts from Code Samples

Writing technical documentation with Asciidoc and Asciidoctor is so much fun. Especially the include macro makes inserting changing content, like source files, a breeze. We only need to maintain the original source file and changes will automatically appear in the generated documentation. We can include only a part of source file using tags. In the source file we add a comment with the following format tag::tagName[] to start the section. We end the section with end::tagName[]. Now in our Asciidoc document we can indicatie the tags we want to include with include::sourceFile[tags=tagName].

Suppose we have the following Groovy source file Sample.groovy. We want to include the method hello() in our technical documentation:

// File: Sample.groovy
package com.mrhaki.blog.groovy

class Sample {

    // tag::helloMethod[]
    String hello() {
        'Asciidoc rules!'
    }
    // end::helloMethod[]

}

In our Asciidoc document we use the following syntax to include only the hello() method:

== Sample Asciidoc

[source,groovy]
.Sample.groovy
----
include::Sample.groovy[tags=helloMethod]
----

This will result in the following HTML if we use Asciidoctor with the pretty-print syntax highlighter:

<div class="listingblock">
<div class="title">Sample.groovy</div>
<div class="content">
<pre class="prettyprint groovy language-groovy"><code>
    String hello() {
        'Asciidoc rules!'
    }
</code>
</pre>
</div>
</div>
</div>

Written with Asciidoctor 0.1.4.