Better documentation with ascciidoc and asciidoctor

This article is just a link to a presentation I published on slideshare, you can check it out here :

Better documentation with ascciidoc and asciidoctor

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 :

• http://powerman.name/doc/asciidoc
• http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
• https://github.com/asciidoctor/asciidoctor-maven-plugin
• http://asciidoctor.org/docs/asciidoc-writers-guide/
• http://asciidoc.the-huck.com/

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

For some time now I have been hearing a lot aboutAsciiDoc as a mean to write documentation but never had the chance to use it...

Recently I stumbled upon AsciiDoctor and since I was about to begin working on a small project with no previous documentation I thought it was the perfect time to try it out..

Documentation is an important part of a project which more often than we would like gets put aside for a great number of reasons. One of them is that we as developpers tend not to like writing documentation...

0.Intro and scope

In this tutorial I will show you how to integrate Asciidoctor class in your Java project and get you started with a small documentation example as well as some tips such as :

• Asciidoc templating using fragments
• Generating a TOC (table of contents) for your documentation
• Integrating images in your asciidoc files
• Code syntax highlighting in your asciidoc files
• Making external links (i.e. _target blank)

Please note that I assume you have some knowledge of Asciidoc so I won't delve into much detail regarding Asciidoc

1. What is AsciiDoc ?

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

2. What is Asciidoctor ?

Asciidoctor is a pure Ruby processor for converting AsciiDoc source files and strings into HTML 5, DocBook 4.5 and other formats. It’s published as a RubyGem and is available under the MIT open source license.

I invite you to take a look to this nice presentation by Dan Allen Discover Zen Writing with Asciidoc which gives you a good overview of AsciiDoc

3. First steps and configuration

First things first go ahead and create a simple maven module let's say a simple JAR for example using the maven archetype plugin or using you favorite IDE

mvn archetype:generate -DgroupId=com.ufasoli -DartifactId=asciidoc-helloworld -DinteractiveMode=false

Once your maven project is created go ahead and create a folder named asciidoc under src/main this is where we will be putting our Asciidoc files

Let's go ahead and create our first asciidoc file under the folder we just created let's name it index.ad and for the moment keep it simple let's just add the page title

= Asciidoctor hello world

So now with our first asciidoc file let's go ahead and configure maven to parse our documentation files and generate HTML documentation files by using the Maven Asciidoctor plugin

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

Now if you run a mvn clean compile you will see an index.html that will be generated under the target/generated-docs folder with an output similar to :

So that's it for the first part of this tutorial, you can find the rest tomorrow on part 2