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:

Sample.groovy

    
        String hello() {
            'Asciidoc rules!'
        }