I have to admit, I'm following the trends. Doing some documentation with Asciidoctor and playing with Docker and if you don't know those 2, you should have a look at them.
Anyway let's dive in. As written in the Asciidoctor documentation, you should first install ruby and then install the asciidoctor gem. Easy right, but here comes asciidoctor-diagram with which you can directly write PlantUML diagrams in your document. It will create and insert the image in the final document for you.
But asciidoctor-diagram requires a JAVA_HOME environment variable because of its dependency of RJB. Everyone has a proper JAVA_HOME set right ? I know it should the case but unfortunately it's not. Then you have to install asciidoctor-pdf if you want to create PDF file directly from the document without using docbook (or equivalent).
All that just to try Asciidoctor, so I suggest you to have a look at the docker container I have published: https://registry.hub.docker.com/u/gscheibel/asciidoctor/
Avoiding to install all the things mentioned above by installing docker isn't too much ? I don't think so because you can use docker for so many other reasons like trying a NoSQL database, an application server etc.
Once you have your docker environment setup, let's start by downloading the image
$ docker pull gscheibel/asciidoctorNext step, running it. The idea is to allow you to have access to the asciidoctor ecosystem as if it were set up in local. Of course you can share your local folder with the container:
$ docker run -it -v <your directory>:/documents/ gscheibel/asciidoctorOf course, don't forget to replace the <your directory> placeholder by the path of the directory you want to map. Now you can easily modify your documents on the host and let use asciidoctor like
$ asciidoctor myDoc.adoc
$ asciidoctor-pdf myDoc.adocOr if you want to use asciidoctor-diagram
$ asciidoctor -r asciidoctor-diagram myDocWithDiagram.adoc
$ asciidoctor-pdf -r asciidoctor-diagram myDocWithDiagram.adocEasy to use and so efficient.
The container's capabilities can easily be improved by adding the stylesheet factory (to create your own theme). If you have ideas, just let me know.