Using Asciidoctor in Java and Spring Boot

Upasana | October 22, 2019 | 3 min read | 18 views

In this tutorial, we will learn how to use Asciidoctor in a Spring Boot based project using Java/Kotlin. We will be converting AsciiDoc to HTML and PDF format.

What is AsciiDoc and Asciidoctor

AsciiDoc is a mature, plain-text format for authoring notes, articles, documentation, books, ebooks, and more.

Asciidoctor is a text processor and toolchain for translating AsciiDoc documents into various formats, including HTML, PDF and ePub.

You can refer to their official documentation to know more.

AsciidoctorJ is java bindings for Asciidoctor which enables accessing Asciidoctor API from java.

Gradle dependencies for AsciidoctorJ

We need to include the below dependencies in our build.gradle file to start using asciidoctorj.

build.gradle

dependencies {
	implementation 'org.asciidoctor:asciidoctorj:2.1.0'
	implementation 'org.asciidoctor:asciidoctorj-pdf:1.5.0-beta.6'
}

bootJar {
    launchScript()
    requiresUnpack '**/jruby-complete-*.jar', '**/asciidoctorj-*.jar', '**/asciidoctorj-pdf-*.jar'  (1)
}

1	We need to specify requiresUnpack inorder to make asciidoctorj work from inside uber jar created by Spring Boot. For more information, checkout this link Configuring libraries that require unpacking

Latest version of asciidoctorj gradle dependencies can be found here:

AsciidoctorJ APIs

org.asciidoctor.Asciidoctor is the main interface for AsciidoctorJ java library. The main methods on this interface are:

convert: this method takes AsciiDoc in string format and converts it to the specified format.
convertFile: this method parses AsciiDoc from provided file and converts it to the specified format.
javaExtensionRegistry: this method is used to register custom processors i.e. inline macro, block macro processor etc.
convertDirectory: this method parse all AsciiDoc files found using DirectoryWalker instance and processes them.

Converting AsciiDoc to HTML and PDF

In the below code snippet, we are converting a given AsciiDoc string into HTML using convertHtml() method call.

AsciidocService.java

import org.asciidoctor.Asciidoctor;
import org.asciidoctor.OptionsBuilder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

import java.io.File;

import static org.asciidoctor.OptionsBuilder.options;

@Service
public class AsciidocService {

    private final Logger logger = LoggerFactory.getLogger(AsciidocService.class);

    private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();

    public void convertHtml() {
        final OptionsBuilder options = options();
        options.inPlace(true);
        options.backend("html");
        String results = asciidoctor.convert("this is test", options);
        logger.info("html results = " + results);
    }
}

Here, the HTML output is returned as the result of invocation.

In order to generate PDF file from an AsciiDoc document, we need to configure options to include the backend as PDF.

AsciiDoc file to Pdf conversion

public void convertPdf() {
    final OptionsBuilder options = options();
    options.inPlace(true);
    options.toFile(new File("test.pdf"));
    options.backend("pdf");

    String results = asciidoctor.convertFile(new File("test.adoc"), options);
    logger.info("pdf results = " + results);
}

In this program, a test.pdf file will be created in the same directory where test.adoc file is present.