Generating a Book with Asciidoctor

1. Introduction

In this quick article, we’ll demonstrate how to generate a book from an AsciiDoc document, and how to customize your book with various style options.

If you’re not familiar with AsciiDoc in Java, you can read our Introduction to AsciiDoctor.

2. Backend Book Type

The simplest way to generate a book with AsciiDoctorj is with Maven like in the previously mentioned article. The only difference is that you have to specify doctype tag and set it to “book”.

<backend>pdf</backend>
<doctype>book</doctype>

With defined doctype, AsciiDoctorj knows that you want to build a book, so it creates:

• A title page
• A table of contents
• The first page of body content
• Parts and chapters

To get mentioned parts, Asciidoc document should have defined title, sections and other parts which are normal for a book.

3. Defining a Custom Style

While writing a book, it’s natural that we want to use some custom styling. It’s possible to do this with AsciiDoc specific formatting language defined in the simple YAML file.

For example, this snippet of code will define how each page in a book will look like. We want to be in the portrait mode, 0.75-inch margin on top and bottom, and 1-inch margin on the sides on A4 paper format:

page:
    layout: portrait
    margin: [0.75in, 1in, 0.75in, 1in]
    size: A4

Also, we can define a custom style for book’s footer and header:

header:
  height: 0.5in
  line_height: 1
  recto_content:
    center: '{document-title}'
  verso_content:
    center: '{document-title}'

footer:
  height: 0.5in
  line_height: 1
  recto_content:
    right: '{chapter-title} | *{page-number}*'
  verso_content:
    left: '*{page-number}* | {chapter-title}

More formatting options can be found on Github page of AsciiDoctorj.

To include the custom theme in a book generation process, we have to define the path where our style file is located. The location is specified in attributes part in pom.xml:

<pdf-stylesdir>${project.basedir}/src/themes</pdf-stylesdir>
<pdf-style>custom</pdf-style>

The first line defines the path where our style is defined and the second line specifies the name of the file without extension.

With these changes, our pom.xml looks like this:

<configuration>
    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
    <outputDirectory>target/docs/asciidoc</outputDirectory>
    <attributes>
        <pdf-stylesdir>${project.basedir}/src/themes</pdf-stylesdir>
        <pdf-style>custom</pdf-style>
    </attributes>
    <backend>pdf</backend>
    <doctype>book</doctype>
</configuration>

4. Generating Book

To generate your book, you just have to run Maven in the project directory, and generated book can be found in target/docs/asciidoctor/ directory.

5. Conclusion

In this tutorial, we showed you how to generate book decorated with simple style with Maven.

As always, the code from this article can be found over on GitHub.