AsciiDoc is a lightweight markup language used to create documentation such as web pages, help guides, and technical content. It can be converted into formats like HTML, PDF, and EPUB using tools like Asciidoctor.
- AsciiDoc is used for writing structured documentation in plain text
- Asciidoctor is a fast processor to convert AsciiDoc into multiple formats
- AsciidoctorJ allows integration of Asciidoctor with Java projects
Steps to Use AsciiDoctor with Maven Project
Step 1: Create Maven Project
- Create a new Maven project.
- Follow standard structure: src/main/java , src/test/java , src/docs/asciidoc
- Add Dependencies in pom.xml
- Add AsciidoctorJ dependency and plugin.
Dependencies:
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>1.5.5</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<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 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
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
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
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:
Explanation: The code shows how to use Asciidoctor in a Maven project to convert AsciiDoc content into PDF and HTML formats. It creates an Asciidoctor instance, performs conversion using methods like convert() and convertFile(), and uses Maven plugins to automate the process, while JUnit tests verify the output.