1. Introduction

This tutorial shows how to start a Java Maven project from scratch and built all the necessary structure to have Asciidoctor capabilities along with spell checking for different languages as part of the project tests.

2. Prerequisites

  • Java Development Kit >= 7

  • Maven >= 3.3.9

3. Creating Base Project Structure

3.1. Create a Maven project

On a terminal execute the following command:

mvn archetype:generate -DgroupId=asciidoctor.doc.demo -DartifactId=book-demo -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

On a terminal cd into the generated folder:

cd book-demo/

The generated folder structure should look like this:

├── pom.xml
└── src
    ├── main
    │   └── java
    │       └── asciidoctor
    │           └── doc
    │               └── demo
    │                   └── App.java
    └── test
        └── java
            └── asciidoctor
                └── doc
                    └── demo
                        └── AppTest.java

The pom.xml file contains at this point the basic project structure.

3.2. Add Asciidoctor to the project

On a text editor, open the pom.xml file and add the following sections:

  • Update the <properties> section with the following content:

   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
     <asciidoctor.maven.plugin.version>1.5.7.1</asciidoctor.maven.plugin.version>
     <asciidoctorj.pdf.version>1.5.0-alpha.16</asciidoctorj.pdf.version>
     <asciidoctorj.version>1.5.8.1</asciidoctorj.version>
     <maven.build.timestamp.format>yyyy-MM-dd HH:mm:ss z</maven.build.timestamp.format>
   </properties>

  • In the <build> section, add the following content after the </pluginManagement> tag:

   <plugins>
     <plugin>
       <groupId>org.asciidoctor</groupId> (1)
       <artifactId>asciidoctor-maven-plugin</artifactId>
       <version>${asciidoctor.maven.plugin.version}</version>

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

       <executions>
         <execution>
           <id>output-html</id> (4)
           <phase>generate-resources</phase>
           <goals>
             <goal>process-asciidoc</goal>
           </goals>
           <configuration>
             <backend>html5</backend>
             <sourceHighlighter>highlight.js</sourceHighlighter>
             <preserveDirectories>true</preserveDirectories>
             <attributes>
               <toc>left</toc>
               <sectanchors>true</sectanchors>
             </attributes>
           </configuration>
         </execution>
         <execution>
           <id>generate-pdf-doc</id> (5)
           <phase>generate-resources</phase>
           <goals>
             <goal>process-asciidoc</goal>
           </goals>
           <configuration>
             <backend>pdf</backend>
             <sourceHighlighter>highlight.js</sourceHighlighter>
             <preserveDirectories>true</preserveDirectories>
             <attributes>
               <pagenums/>
               <toc/>
               <idprefix/>
               <idseparator>-</idseparator>
             </attributes>
           </configuration>
         </execution>
       </executions>

       <configuration> (6)
         <attributes>
           <project-version>${project.version}</project-version>
           <revdate>${maven.build.timestamp}</revdate>
           <sectnums>true</sectnums>
           <icons>font</icons>
         </attributes>
       </configuration>
     </plugin>
   </plugins>
1 Reference to asciidoctor-maven-plugin.
2 Dependencies used by the asciidoctor-maven-plugin.
3 Provides PDF export capabilities to the project.
4 Configuration for HTML export.
5 Configuration for PDF export.
6 Global configuration for both executions.

3.3. Create your first AsciiDoc file

  • Create the default AsciiDoc folder:

   mkdir src/main/asciidoc

  • Inside src/main/asciidoc folder create the file index_en.adoc with the following content:


  
1
2
3
4
5
6
7


  
   = Tutorial (1)
   :nofooter: (2)
   Author     (3)
   {project-version}, {revdate} (4)

   == Chapter 1 (5)
   This is my firt chapter.
1 Set the document main Header.
2 Removes from the document the auto generated header.
3 Author name.
4 Maps the project version and revision date from the pom.xml file.
5 Set the first document sub header.

3.4. Generate your first HTML and PDF files

  • On a terminal execute the following command:

   mvn clean  generate-resources

  • The following files will be generated under the folder target/generated-docs/

    • index_en.html

    • index_en.pdf

The generated html version should look similar to:

image