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.

Table of contents:

  • What is AsciiDoc and Asciidoctor

  • Gradle dependencies in Spring Boot

  • Spring boot specific settings

  • AsciidoctorJ API

  • Convert AsciiDoc to Html5

  • Converting AsciiDoc to PDF

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.

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

bootJar {
    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:


this method takes AsciiDoc in string format and converts it to the specified format.


this method parses AsciiDoc from provided file and converts it to the specified format.


this method is used to register custom processors i.e. inline macro, block macro processor etc.


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.
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.OptionsBuilder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;


import static org.asciidoctor.OptionsBuilder.options;

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();
        String results = asciidoctor.convert("this is test", options);"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.toFile(new File("test.pdf"));

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

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

Top articles in this category:
  1. 2factor SMS in Spring Boot App
  2. how to enable asciimath formula using mathjax in asciidoctorJ
  3. Integrating PayUmoney with your Java Server Side
  4. Asciidoc: How to use nofollow option in asciidoc document
  5. Integrating PayUmoney Webhooks with your Java backend
  6. Reverting default shell to bash from Zsh in Mac OS Catalina

Recommended books for interview preparation:

Find more on this topic:
Buy interview books

Java & Microservices interview refresher for experienced developers.