November 25, 2014

Awesome Asciidoctor: Using Document Fragments

Normally all Asciidoc files are processed and transformed to output files by Asciidoctor. But if we start the file name with an underscore (_) the file is not transformed to an output file. This is very useful, because we can define some Asciidoc document fragments and include them in other Asciidoc files, but in the output directory the document fragment is not generated.

Let's create two Asciidoc files. One is _attrs.adoc which is a document fragment file that is used in sample.doc:

// File: _attrs.adoc
:blogger_url: http://mrhaki.blogspot.com
:blogger_tag: Aweseome Asciidoctor
:author: mrhaki
// File: sample.adoc

== Sample

Asciidoctor handles files starting
with an underscore (`_`) differently. The file is
not processed, but can be used in other Asciidoc

More {blogger_url}[blog posts] about
{blogger_tag} available written by {author}.

From the command line we can invoke the asciidoctor command. We also check the directory and see there is only the file sample.html:

$ asciidoctor sample.adoc
$ ls
_attrs.adoc sample.adoc sample.html

The following screenshot shows how the sample.html looks like in a web browser:

Written with Asciidoctor 1.5.1.