This is an example of how to use Asciidoctor Diagram to generate diagrams in Maven projects and include them in README and other Markdown files. It is based on the asciidoctor-maven-examples
Asciidoctor Diagram is a set of Asciidoctor extensions that support generating diagrams from multiple diagram languages including AsciiToSVG, BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag), Ditaa, Erd, GraphViz, Mermaid, Msc, PlantUML, Shaape, SvgBob, Syntrax, UMLet, Vega, Vega-Lite and WaveDrom.
See their website website for more details. Many of these tools do not work out of the box and must be installed separately to be available at build time, but a few them are available out of the box, see below.
We might include this plugin configuration in the Sling Parent POM if we start using it in several modules.
In this example project, the Asciidoctor Maven Plugin runs on every build as the corresponding diagrams Maven profile is enabled by default. Depending on the diagram generators used, running the plugin might change the generated images every time, which is not convenient.
The idea is to store the diagrams under src/docs/asciidoc and have the Asciidoctor Maven Plugin convert them and store the results under src/docs/generated-diagrams, so the generated images can be committed to be used in README and other Markdown files.
Here are example diagrams generated by the asciidoc documents found under src/docs/asciidoc in this project.
The following diagram generation tools should work on a standard Maven setup.
Ditaa converts ASCII art diagrams to (much) nicer graphics.
See http://ditaa.sourceforge.net/#usage for usage information.
PlantUML supports lots of diagram types: sequence, use case, class, activity, component, state, object, deployment, timing, network, wireframe and more.
See https://plantuml.com and https://crashedmind.github.io/PlantUMLHitchhikersGuide/
The following diagram generation tools must be installed separately to be available at build time. If they are missing, the Maven plugin outputs descriptive error messages but does not fail the build.
The more-syntaxes.adoc document has more examples in various syntaxes, most or all fail to build unless you have installed the required tools.
This one requires the dot command of Graphviz to be available at build time.
Vega can be installed with npm install -g vega-cli so that might be a reasonable option if we need more complex diagrams.