Diagrams
General
Diagrams are useful to visualize the structure of a system or processes.
Metanorma supports the LutaML and PlantUML diagramming tools, for creation of different kinds of diagrams directly in a Metanorma document.
LutaML
Please refer to documentation for the LutaML UML plugin.
PlantUML
Prerequisites
If you are using Metanorma installed through one of the supported installation mechanisms (e.g. Homebrew, Snap, Chocolatey, Docker), this feature is by default available.
If you are using the development install (e.g. via Ruby gems), you need to have PlantUML installed in order to use this feature. Specifically, you must have an accessible executable called plantuml in your terminal path.
Please refer to the official PlantUML site for installation instructions.
The recommended manner to install PlantUML on macOS is through Homebrew, and on Windows via Chocolatey.
Adding a diagram
To add one or more diagrams in a Metanorma document:
- Begin a new literal block (delimited by
....) and use the attribute[plantuml]. - Begin the diagram with
@startuml. - Enter your diagram using the PlantUML notation.
- End the diagram with
@enduml.
Example:
[plantuml]
....
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
....The [plantuml] block is automatically processed by PlantUML to transform its text input into a target image that is embedded in place of the block.
By default, the PNG format is used. To change the output format for PlantUML to SVG, use the document attribute :plantuml-image-format: svg [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.9]
The images are stored in a plantumlimages directory relative to the current path [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.9].
plantuml directory, or in the directory specified by the :imagesdir: document attribute.