Posts

Showing posts from June, 2014

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

Image
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 contentThere 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 compositionPersonally 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 t…

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

Image
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 documentationIntegrating images in your asciidoc filesCode syntax highlighting in your asciidoc filesMaking external links (i.e. _target blank)Please note that I assume you have some knowledge of Asciidoc so I …