How do I add a PlantUML diagram?

Question
Answer
Script
Tested by
See also

PlantUML is used throughout ORE Studio for architecture diagrams, component models, and information-flow illustrations. Every diagram follows the same file conventions: a GPL licence header, @startuml / @enduml delimiters, and a title line. The PNG output lives alongside the .puml source and is embedded in org-mode with #+caption: and optional #+attr_html: / #+attr_latex: lines. For the system-level diagram see System Model; for component diagrams see any projects/<component>/modeling/<component>.puml.

Question

How do I add a new PlantUML diagram to an org-mode document?

Answer

1. Verify PlantUML is installed

plantuml -version

On Ubuntu/Debian: sudo apt install plantuml. Check the LLM instructions for the exact version used in CI.

2. Scaffold the `.puml` file

Use compass add diagram to create a properly headed skeleton. Pass the target directory with --parent-dir and an optional --title:

projects/ores.compass/compass.sh add diagram my_diagram \
    --parent-dir doc/meta \
    --title "My Diagram Title"

This writes doc/meta/my_diagram.puml with the standard GPL licence header, @startuml, the title line, and @enduml. The file is immediately compilable.

3. Edit the `.puml` source

Open the generated file and add diagram content between the title line and @enduml. Example using a simple component diagram:

' (example — do not copy the src block itself, just the .puml content)
@startuml

title My Component

component [Service A] as A
component [Service B] as B

A --> B : NATS

@enduml

See plantuml.com/component-diagram for the full syntax reference.

4. Export to PNG

plantuml -tpng doc/meta/my_diagram.puml

This produces doc/meta/my_diagram.png alongside the source file. Re-run after every edit; the PNG is committed to the repo so the site build does not need PlantUML at CI time.

5. Embed in the org-mode document

Place the PNG reference immediately after any context it illustrates. Use #+caption: for figure captions and #+attr_html: :width 100% when the diagram should fill the page width in the HTML export:

#+caption: One-sentence description of what the diagram shows.
#+attr_html: :width 100%
#+attr_latex: :width \textwidth
[[proj:doc/recipes/plantuml/my_diagram.png]]

For narrower diagrams (e.g. lifecycle flows), omit the attr lines and let the image render at its natural size:

#+caption: Task lifecycle state machine.
[[proj:doc/recipes/plantuml/task_lifecycle.png]]

6. Commit both files

Always commit the .puml source and the generated .png together so the repo is self-contained:

git add doc/meta/my_diagram.puml doc/meta/my_diagram.png

Script

compass add diagram <slug> [--parent-dir DIR] [--title TITLE]

Scaffolds <slug>.puml with the standard GPL licence header, @startuml, a title derived from the slug (or --title if given), and @enduml.

Tested by

Manual smoke test: run compass add diagram smoke_test --parent-dir /tmp, then plantuml -tpng /tmp/smoke_test.puml and confirm the PNG is produced without errors.