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 :
