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