Generating a Book with Asciidoctor

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Distributed systems often come with complex challenges such as service-to-service communication, state management, asynchronous messaging, security, and more.

Dapr (Distributed Application Runtime) provides a set of APIs and building blocks to address these challenges, abstracting away infrastructure so we can focus on business logic.

In this tutorial, we'll focus on Dapr's pub/sub API for message brokering. Using its Spring Boot integration, we'll simplify the creation of a loosely coupled, portable, and easily testable pub/sub messaging system:

>> Flexible Pub/Sub Messaging With Spring Boot and Dapr

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>