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

Let us see the important java files and concepts

SampleDemoOfGeneratingPDF_HTML.java

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

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.