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
include::_attrs.adoc[]

== Sample

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

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.

Original article