Using Asciidoctor in Java and Spring Boot

Carvia Tech | October 22, 2019 | 3 min read | 6 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. Integrating PayUmoney with your Java Server Side
  2. Integrating PayUmoney Webhooks with your Java backend
  3. how to enable asciimath formula using mathjax in asciidoctorJ
  4. Asciidoc: How to use nofollow option in asciidoc document
  5. Reverting default shell to bash from Zsh in Mac OS Catalina


Find more on this topic:
Misc IT & Integration image
Misc IT & Integration

Misc IT integration topics - Payment Gateways, SMS gateways, Email Servers, Hosting Solutions etc.

Last updated 1 week ago


Recommended books for interview preparation:

This website uses cookies to ensure you get the best experience on our website. more info