Introduction to Asciidoctor in Java

1. Introduction

In this article, we’ll make a quick introduction on how to use Asciidoctor with Java. We’ll demonstrate how to generate HTML5 or PDF from an AsciiDoc document.

2. What Is AsciiDoc?

AsciiDoc is a text document format. It can be used for writing documentation, books, web pages, man pages and many other.

Since it’s very configurable, AsciiDoc documents can be converted into many other formats like HTML, PDF, man pages, EPUB, and others.

Because AsciiDoc syntax is quite basic, it has become very popular with a large support in various browser plugins, plugins for programming languages and other tools.

To learn more about the tool, we suggest reading the official documentation where you can find many useful resources for learning proper syntax and methods for exporting your AsciiDoc document to other formats.

3. What Is Asciidoctor?

Asciidoctor is a text processor for converting AsciiDoc documents into HTML, PDF and other formats. It’s written in Ruby and packaged as a RubyGem.

As mentioned above, AsciiDoc is a very popular format for writing documentation, so you can easily find Asciidoctor as a standard package in many GNU Linux distribution like Ubuntu, Debian, Fedora, and Arch.

Since we want to use Asciidoctor on the JVM, we’ll talk about AsciidoctorJ – which is Asciidoctor with Java.

4. Dependencies

To include AsciidoctorJ package in our application, the following pom.xml entry is needed:

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>2.5.7</version>
</dependency>
<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj-pdf</artifactId>
    <version>2.3.4</version>
</dependency>

Latest versions of libraries can be found here and here.

5. AsciidoctorJ API

The entry point for AsciidoctorJ is the Asciidoctor Java interface.

Those methods are:

• convert – parses AsciiDoc document from a String or Stream and converts it to the provided format type
• convertFile – parses AsciiDoc document from a provided File object and converts it to the provided format type
• convertFiles – same as previous, but method accepts multiple File objects
• convertDirectory – parses all AsciiDoc documents in provided folder and converts them to the provided format type

5.1. API Usage in Code

To create an Asciidoctor instance, you need to retrieve the instance from the provided factory method:

import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;
..
//some code
..
Asciidoctor asciidoctor = create();

With retrieved instance, we can convert AsciiDoc document very easily:

String output = asciidoctor
  .convert("Hello _Baeldung_!", new HashMap<String, Object>());

If we want to convert a text document from the file system, we’ll use the convertFile method:

String output = asciidoctor
  .convertFile(new File("baeldung.adoc"), new HashMap<String, Object>());

For converting multiple files, the convertFiles method accepts List object as a first parameter and returns arrays of String objects.
More interesting is how to convert a whole directory with AsciidoctorJ.

As mentioned above, to convert a whole directory – we should call the convertDirectory method. This scans the provided path and searches for all files with AsciiDoc extensions (.adoc, .ad, .asciidoc, .asc) and converts them. To scan all files, an instance of the DirectoryWalker should be provided to the method.

Currently, Asciidoctor provides two built-in implementations of mentioned interface:

• AsciiDocDirectoryWalker – converts all files of given folder and its subfolders. Ignores all files starting with “_”
• GlobDirectoryWalker – convert all files of given folder following a glob expression

String[] result = asciidoctor.convertDirectory(
  new AsciiDocDirectoryWalker("src/asciidoc"),
  new HashMap<String, Object>());

Also, we can call convert method with provided java.io.Reader and java.io.Writer interfaces. Reader interface is used as the source, and Writer interface is used for writing converted data:

FileReader reader = new FileReader(new File("sample.adoc"));
StringWriter writer = new StringWriter();
 
asciidoctor.convert(reader, writer, options().asMap());
 
StringBuffer htmlBuffer = writer.getBuffer();

5.2. PDF Generation

To generate a PDF file from an Asciidoc document, we need to specify the type of the generated file in options. If you look a little more carefully into the previous examples, you’ll notice that second parameter of any convert method is a Map – which represents options object.

We’ll set the in_place option to true so that our file is automatically generated and saved to the file system:

Map<String, Object> options = options()
  .inPlace(true)
  .backend("pdf")
  .asMap();

String outfile = asciidoctor.convertFile(new File("baeldung.adoc"), options);

6. Maven Plugin

In the previous section, we showed how we can generate PDF file directly with your own implementation in Java. In this section, we will show how you to generate PDF file during Maven build. Simiar plugins exist for Gradle and Ant.

To enable PDF generation during the build, you need to add this dependency to your pom.xml:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.2</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>2.3.4</version>
        </dependency>
    </dependencies>
</plugin>

The latest version of Maven plugin dependency can be found here.

6.1. Usage

To use the plugin in the build, you have to define it in the pom.xml:

<plugin>
    <executions>
        <execution>
            <id>output-html</id> 
            <phase>generate-resources</phase> 
            <goals>
                <goal>process-asciidoc</goal> 
            </goals>
        </execution>
    </executions>
</plugin>

Since the plugin doesn’t run in any specific phase, you have to set the phase where you want to start it.

As with the Asciidoctorj plugin, we can use various options for PDF generation here as well.

Let’s have a quick look at the basic options while you can find other options in the documentation:

• sourceDirectory – the location of directory where you have Asciidoc documents
• outputDirectory – the location of the directory where you want to store generated PDF files
• backend – the type of the output from Asciidoctor. For PDF generation set for pdf

This is an example how to define basic options in the plugin:

<plugin>
    <configuration>
        <sourceDirectory>src/main/doc</sourceDirectory>
        <outputDirectory>target/docs</outputDirectory>
        <backend>pdf</backend>
    </configuration>
</plugin>

After running the build, the PDF files can be found in the specified output directory.

7. Conclusion

Even though AsciiDoc is very easy to use and understand, it’s a very powerful tool for managing documentation and other documents.

In this article, we demonstrated a simple way to generate HTML and PDF files from AsciiDoc document.