Metanorma: Aequitate Verum

Author’s documentation

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:

  1. Begin a new literal block (delimited by …​.) and use the attribute [plantuml].

    The compiler now knows that PlantUML syntax follows.

  2. Begin the diagram with @startuml.

  3. Enter your diagram using the PlantUML notation.

  4. 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
....

Metanorma when encountered with a [plantuml] block will automatically invoke PlantUML to transform your text input into a PNG image. The images are stored in a plantuml directory relative to the current path.

  • Visit the PlantUML website to learn more about PlantUML and what kinds of diagrams it supports.