How to Use AsciiDoctor with Maven Project in Java?

AsciiDoc is nothing but a text document mainly used to prepare help documents, and documentation on various concepts like documenting web pages, product review pages, etc. AsciiDoc documents can be converted into formats like PDF or HTML or EPUB etc.,

AsciiDoctor

It is a text processor involved in converting AsciiDoc documents into PDF or HTML. As we want to do the coding part with Java, let us see AsciiDoctorJ and see what are dependencies required to use that in the project.

Example Maven Project

Dependencies:

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>1.5.5</version>
</dependency>

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj-pdf</artifaDocctId>
    <version>1.5.0-alpha.15</version>
</dependency>

To use the plugin in the build, we need to add as follows

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

And also we need to specify the path where the converted files are placed into

<plugin>
      <configuration>
                    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                    <outputDirectory>target/docs/asciidoc</outputDirectory>
                    <attributes>
                        <pdf-stylesdir>${project.basedir}/src/themes</pdf-stylesdir>
                        <pdf-style>custom</pdf-style>
                    </attributes>
                    <backend>pdf</backend>
                    <doctype>book</doctype>
      </configuration>
</plugin>

Let us see about AsciidoctorJ API. AsciiDoctor Java interface has the below methods

• convert – It parses AsciiDoc document from a given string or inputstream and will convert in the specified format.
• convertFile – From a file object, parses AsciiDoc document and will convert in the specified format.
• convertFiles – Here choice of multiple file selection, parsing, and converting in the specified format.
• convertDirectory – Parses all the AsciiDoc documents in the mentioned folder and converts them in the specified format.

Let us start exploring by starting with the project structure

Project Structure:

As this is a maven project, for doing the project, let us see the dependencies via

pom.xml

XML

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0"
    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://maven.apache.org/POM/4.0.0
                        https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <artifactId>asciidoctor</artifactId>
    <name>asciidoctor</name>

    <parent>
        <groupId>com.gfg</groupId>
        <artifactId>parent-modules</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj</artifactId>
            <version>${asciidoctorj.version}</version>
        </dependency>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>${asciidoctorj-pdf.version}</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>${asciidoctor-maven-plugin.version}</version>
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>${asciidoctorj-pdf.plugin.version}</version>
                    </dependency>
                </dependencies>
                <executions>
                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                    <outputDirectory>target/docs/asciidoc</outputDirectory>
                    <attributes>
                        <pdf-stylesdir>${project.basedir}/src/themes</pdf-stylesdir>
                        <pdf-style>custom</pdf-style>
                    </attributes>
                    <backend>pdf</backend>
                    <doctype>book</doctype>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <properties>
        <asciidoctor-maven-plugin.version>1.6.0</asciidoctor-maven-plugin.version>
        <asciidoctorj.version>1.5.6</asciidoctorj.version>
        <asciidoctorj-pdf.version>1.5.0-alpha.15</asciidoctorj-pdf.version>
        <asciidoctorj-pdf.plugin.version>1.5.0-alpha.15</asciidoctorj-pdf.plugin.version>
        <project.java.version>1.8</project.java.version>
    </properties>

</project>

Let us see the important java files and concepts

SampleDemoOfGeneratingPDF_HTML.java

Java

import static org.asciidoctor.Asciidoctor.Factory.create;
import static org.asciidoctor.OptionsBuilder.options;

import java.io.File;
import java.util.HashMap;
import java.util.Map;

import org.asciidoctor.Asciidoctor;

public class SampleDemoOfGeneratingPDF_HTML {

    private final Asciidoctor sampleAsciiDoctor;

    SampleDemoOfGeneratingPDF_HTML() {
        sampleAsciiDoctor = create();
    }

    public void generationOfPDFFromString(final String inputString) {

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


        String resultantFile = sampleAsciiDoctor.convertFile(new File("sample.adoc"), options);
    }

    String generationOfHTMLFromString(final String inputString) {
        return sampleAsciiDoctor.convert("Hello _Geeks_!", new HashMap<String, Object>());
    }
    public static void main(String args[]) {
        new SampleDemoOfGeneratingPDF_HTML().generationOfPDFFromString("hello");
    }
}

For creating an Asciidoctor  instance, we need to use as 

Asciidoctor sampleAsciiDoctor= create();

Converting AsciiDocument easily as follows

String result = sampleAsciiDoctor.convert("Hello _Geeks_!", new HashMap<String, Object>());

From the file system means

String resultantFile = sampleAsciiDoctor.convertFile(new File("sample.adoc"), options);
// Here we need to specify the options, i.e. in which format it has to get converted
Map<String, Object> options = options().inPlace(true)
          .backend("pdf")
          .asMap(); 

Now to see this as a demo, let us assume we have a “sample.adoc” file under src/docs/asciidoc directory

On execution of the java file, we can able to get a pdf document to get generated under target/docs/asciidoc directory

Let us test the same via the JUNIT part as well

SampleAsciidoctorDemoIntegrationTest.java

Java

import org.junit.Assert;
import org.junit.Test;

public class SampleAsciidoctorDemoIntegrationTest {

    @Test
    public void givenString_whenConverting_thenResultingHTMLCode() {
        final SampleDemoOfGeneratingPDF_HTML asciidoctorDemo = new SampleDemoOfGeneratingPDF_HTML();
        Assert.assertEquals(asciidoctorDemo.generationOfHTMLFromString("Hello _Geeks!"), "<div class=\"paragraph\">\n<p>Hello <em>Geeks</em>!</p>\n</div>");
    }
}

Output of JUnit:

Conclusion

AsciiDOC is a powerful tool for managing documents and by using AsciiDOCJ we have seen how to convert that to PDF and HTML. Necessary dependencies are added to the project and via a sample project, it is executed.