Asciidoc Features

Table of Contents

• Requirements
• How to generate documentation files
• Example catalog
• Showing PlantUML diagrams on GitHub

For more information look at the official repo Asciidoctor-maven-examples There you find more and comprehensive examples.

Asciidoctor User Manual

asciidoctor-maven-plugin docs

Requirements

For using plantuml you have to install Graphviz

How to generate documentation files

Table 1. Ho to start

command	description
mvn	the default phase "generate-resources" will be executed for all modules
cd asciidoctor-pdf mvn	the default phase "generate-resources" will be executed for one submodules
mvn clean generate-resources	the target folder will be removed and the default phase "generate-resources" for all modules will be executed for all submodules
cd asciidoctor-pdf mvn clean generate-resources	the target folder will be removed and the default phase "generate-resources" for this submodules will be executed for all submodules
cd asciidoctor-pdf mvn clean package	the target folder will be removed and the doc will be generated and the source code compiled and packaged for all submodules. Use Apache Shade for including the dependencies in the jar and creating the manifest-file.

Tip	cleaning the target folder is always a good idea

Example catalog

asciidoctor-pdf

Demonstrates how to convert AsciiDoc to pdf using the Asciidoctor Maven plugin.
The generated documents (pdf, html5) are located in the target folder

Showing PlantUML diagrams on GitHub

Usually, PlantUML diagrams are not rendered on Github repository overviews. However there is a neat workaround involving PlantUML-render-servers to make diagrams visible.

Step 1: Store your diagram in a separate file:

For example contents of assets/example.iuml:

@startuml
Class01 <|-- Class02
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 -- Class10
@enduml

On your desktop, graphviz usually renders PlantUML diagrams, but in browsers, this does not work.

To get around this, PlantUML provides instructions on how to host a server which turns a .iuml file into an image which can be displayed.

Luckily for us, there are a lot of publicly available servers to render your diagrams. For instance, the official PlantUML server at http://www.plantuml.com/plantuml/

Step 2: Embedding an Image

In combination with raw.githubusercontent.com we can now feed the server the diagram file to render our image for us.

For example, the source of assets/example.iuml would be:

https://raw.githubusercontent.com/Maxwahl/asciidoctor/master/assets/example.iuml

Now we embed the image with the following line:

image::http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/Maxwahl/asciidoctor/master/assets/example.iuml[Example]

This results in: