Asciidoctor maven integration : introduction to asciidoctor and maven asciidoctor plugin part 2/2

This is the second part of the Asciidoctor maven integration tutorial part 1/2 where we explore some of Asciidoctor cool features

4. Additional cool formatting elements and content

There are plenty of nice cheat-sheets out there that resume much better all the cool stuff you can do with (see 5. Some useful links) so I will just list here a few tips to get you started

4a. Asciidoc files inclusion or composition

Personally when writing documentation I like to create a separate file for each topic and then include them in an a big index file (you can do this otherwise if you prefer) this can easily be done using the include macro

Let's create a new Asciidoc page named topic1 and add some content to it

= Topic 1

== Intro

This page describes some information related to topic1

and now include the newly created page using the include macro

= Asciidoctor hello world



include::topic1.ad[]

After re-compiling the code you should end up with the content of the file topic1.ad inside the index.html file

4b. Table of contents (TOC)

Asciidoctor has a lot of macros and attributes that help you when writing documentation, the full list of attributes can be found here

Attributes are configured as child tags of the attributes XML tag under the maven asciidoctor plugin. To enable the table of contents while providing a TOC level we will use the toclevels attribute, since once you start writing a lot of documentation you could end up with a pretty big HTML document it's a good idea to enable the creation of anchors using the setanchors attribute



  
     
          org.asciidoctor
          asciidoctor-maven-plugin
          ${version.asciidoctor}
          
              
                 output-html
                 generate-resources
                 
                     process-asciidoc
                 
                 
                     html
                     book                    
                     
                          
                          true
                          
                          3
                     
                 

               
           
      
  


Once you configured the maven plugin it's time to add the :toc: attribute to the index.ad header

Please be aware within the the first lines of a document known as document header spacing and markup are important as they have special meaning and are handled differently by the asciidoc parsing engine

, for more information on the document header please check the documentation here

= Asciidoctor hello world
:toc:


include::topic1.ad[]

Once the documentation files generated the result should be pretty close to the one in the picture below :

Please note : Not all attributes are supported through the maven asciidoctor plugin so you have to play a bit with the maven configuration to see which ones are supported.
4c. Adding images in your documentation

Everyone knows a picture is worth 1000 words so why don't add some pretty pictures to your documentation

By default when generating the documentation files containing images the asciidoctor plugin will prefix all image paths with images/ this of course can be changed but I usually leave it with the default option

We will now add an images folder to our maven project under src/main/resources/images and put an image of your choice inside of it in my case asciidoc-logo.png

Once this is done let's add our image to our document

= Topic 1

== Intro

This page describes some information related to topic1.

Asciidoc is cool

image::asciidoc-logo.png[Asciidoc logo]

Now we have included an image in our doc file but we're not done yet, you need to instruct maven to copy our images folder to the generated-docs target folder

 
...
        
            
                
                src/main/resources/images
                ${build.directory}/generated-docs/images
            
  .....


4d. Code syntax highlighting

Code syntax highlighting is very important when writing documentation since it helps with the readability. Asciidoc currently supports 4 frameworks to handle your code highlighting

  • coderay
  • prettify
  • highlightjs
  • pygments (not currently supported by maven asciidoctor plugin)

For this tutorial let's say we will use coderay so we first need to activate the syntax highlighting in the maven POM file :



  
      
          org.asciidoctor
          asciidoctor-maven-plugin
          ${version.asciidoctor}
          
             
                 output-html
                 generate-resources
                 
                    process-asciidoc
                 
                 
                      
                      coderay
                      html
                      book

                      
                         
                         true
                         3
                     

                 
              
          
       
    
  

Once our maven configuration is done we can add some source code to our docs, the syntax is pretty straightforward in it's most basic form you just put [source, language] and you surround your code with ---- like so :

[source,java]
----
public class HelloWorld{

   public static void main(String[] args){
      System.out.println("Hello World");
   }
}
----

Once your docs file regenerated you should see something like this :

4e. External links (target _blank)

Whenever I'm reading an HTML documentation containing a link I prefer it when the link opens automatically in a new tab i.e.target="_blank"

This can be achieved using link attributes however by default in Asciidoc this feature is disabled; luckily you just need one small line in your pom.xml file to enable this feature with an attribute


  
      
          org.asciidoctor
          asciidoctor-maven-plugin
          ${version.asciidoctor}
          
             
                 output-html
                 generate-resources
                 
                    process-asciidoc
                 
                 
                      
                      coderay
                      html
                      book

                      
                         
                         true
                         3
                         
                        true
                     

                 
              
          
       
    
  

Now you can go ahead an add your links withe


http://powerman.name/doc/asciidoc[Asciidoc cheatsheet, window="_blank"]


So this concludes this 2 part introductory tutorial to Asciidoctor and maven integration ; have fun writing cool documentation!

5. Some useful links

As usual you can find the code source for this tutorial over github here

Below is a list of useful links to help you with Asciidoctor such as cheatsheet or general documentation :

Popular posts from this blog

Multi-hop ssh tunnel - howto : Creating a SSH tunnel with port forwarding between multiple hosts

Spring boot and spring data jpa tutorial - A sample application using spring 4.0 spring boot and JPA (part 2/2)

Scala : easily load an parse configuration files