Diagrams

1. Introduction

Yawg supports the inclusion of PlantUML diagrams in AsciiDoc documents. Support for PlantUML diagrams is provided internally by Asciidoctor through the Asciidoctor Diagram extension.

There are two possible ways to include a PlantUML diagram inside an AsciiDoc document.

Embedded diagrams — The diagram is defined in a literal block, and is part of the AsciiDoc document itself.
External diagrams — The diagram is defined in a block macro that imports the contents of an external PlantUML file.

The following sections address these two options in more detail.

2. Embedded diagrams

With embedded PlantUML diagrams, the diagram is defined in a literal block. This means the PlantUML content defining the diagram is part of the AsciiDoc file itself.

Using embedded diagrams is fine when the PlantUML definition is short and the diagram is only intended to be used to be included in the final baked HTML document. For complex diagrams with longer definitions it is recommeded to have the diagram in its own dedicated PlantUML file. This is described in the next section.

The figure below contains an example diagram defined in a literal block.

Figure 1. Example of embdedded PlantUML diagram defined in a literal block in the AsciiDoc source file.

The AsciiDoc markup that resulted in the above diagram follows.

[plantuml,Diagram-InlineExample,format=svg]
....
class Car

Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns
....

3. External diagrams

It is also possible to have PlantUML diagrams imported from external files. The plantuml block macro is used in this case.

Defining a PlantUML diagram in its own dedicated file is preferable when the PlantUML definition is long. This helps with keeping the Asciidoc content mostly with actual text content. It is also the natural solution if the diagram also needs to be processed by other tools.

We now show an example of using the plantuml block macro. The figure below contains a diagram defined in its own dedicated file.

Figure 2. Example PlantUML diagram contained in an external file.

The AsciiDoc markup that resulted in the above diagram follows.

.Example PlantUML diagram contained in an external file.
plantuml::Diagram-Example.puml[Diagram-Example,svg]

The main argument for the plantuml block macro is the name of the file containing the PlantUML diagram definition. That is actually a file system path relative to the AsciiDoc source file. In our example the Diagram-Example.puml file is contained in the same directory as the AsciiDoc source file with the content of this page. You can download that file to inspect its contents from here.