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.

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.


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: