1. Introducción

Este tutorial muestra cómo iniciar un proyecto Java Maven desde cero y construyó toda la estructura necesaria para tener capacidades Asciidoctor junto con la revisión ortográfica de diferentes idiomas como parte de las pruebas del proyecto.

2. Prerequisitos

  • Java Development Kit >= 7

  • Maven >= 3.3.9

3. Crear la estructura base del proyecto

3.1. Crear un nuevop proyecto con Maven

En una terminal ejecutar el siguiente comando:

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

En una termainl cd en el directorio generado en el paso anterior:

cd book-demo/

La estructura de diretorios generados debe ser igual a esta:

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

El archivo pom.xml contiene la información básica del proyecto recien creado.

3.2. Agregar Asciidoctor al proyecto

En un editor de texto, abrir el archivo pom.xml y realizar las siguiente modificaciones:

  • Actualizar la sección <properties> con el siguiente contenido:

   <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>

  • En la sección <build>, agregar el siguiente contenido despues de la etiqueta: </pluginManagement>

   <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 Referencia al plugin asciidoctor-maven-plugin.
2 Dependencias utilizadas por el plugin asciidoctor-maven-plugin.
3 Provee PDF export al proyecto.
4 Configuración para reportes en formato HTML.
5 Configuración para reportes en formato PDF.
6 Configuración gobal para ambos executions.

3.3. Creación de tu primer documento AsciiDoc

  • Crea el directorio por defecto de donde almacenaras tus archivos AsciiDoc (.adoc):

   mkdir src/main/asciidoc

  • Dentro del directorio src/main/asciidoc crea un archivo con nombre index_en.adoc y agrega el siguiente contenido:


  
1
2
3
4
5
6
7
8


  
   = Tutorial (1)
   :nofooter: (2)
   :toc-title: Tabla de Contenidos (3)
   Autor     (4)
   {project-version}, {revdate} (5)

   == Capítulo 1 (6)
   Este es mi primer capítulo.
1 Define el encabezado y nombre principal del documento.
2 Remueve del documento el pie de página que se genera por defecto.
3 Sobre escribe el valor por defecto (Table content) del título de la tabla de contenidos.
4 Nombre del autor del documento.
5 Mapeo de la versión y fecha de revisión del documento obtenido a partir del archivo pom.xml.
6 Indica el primer sub encabezado del documento.
Debes respetar que antes del header principal no haya texto, esto ayuda a que durante el proceso de renderización los parámtetros del documento (líneas 2 a la 5) sean efectivos.

3.4. Generación de tu primer documento en formatos HTML y PDF

  • En la terminal ejecuta el siguiente comando:

   mvn clean  generate-resources

  • Los archivos para cada formato se generan en el folder: target/generated-docs/

    • index_en.html

    • index_en.pdf

La version html generada es similiar a la siguiente imagen:

image