Task: Add PlantUML recipe and extend codegen with puml scaffold
This page documents a task in the PlantUML integration: recipe and codegen scaffold story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Two deliverables: (1) a recipe doc that walks a developer through adding a
PlantUML diagram to any org-mode document — from writing the .puml source
to exporting the PNG and embedding it in org-mode with correct figure
metadata; (2) a compass add diagram <slug> sub-command that scaffolds a
.puml file with the standard AGPL licence header, @startuml /
@enduml, and the shared skin/style preamble, matching the convention of
existing .puml files in the repository. Existing diagrams without the
standard header are updated.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | PlantUML integration: recipe and codegen scaffold |
| Now | Complete. |
| Waiting on | Nothing. |
| Next | None. |
| Last touched | 2026-05-28 |
Acceptance
doc/recipes/plantuml/how_do_i_add_a_plantuml_diagram.orgexists (org-roam ID, v2 frontmatter) and covers: prerequisites, writing.pumlsource, runningplantumlto export PNG, embedding via#+attr_html:/#+attr_latex:/#+caption:in an org-mode file.compass add diagram <slug>scaffolds<slug>.pumlwith the standard header; the skeleton compiles without errors underplantuml.- All existing
.pumlfiles in the repo have the standard licence header.
Plan
(Transient implementation strategy. Written when work starts;
distilled into the parent story's * Decisions and cleared when the
task closes. Plans do not outlive their task.)
Notes
PRs
| PR | Title |
|---|---|
| 888 | [doc,compass] PlantUML recipe, compass add diagram sub-command, and topic inventory |
Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | _has_standard_puml_header defined but never used (medium pri) |
compass.py | Fixed | Function removed; scaffold always writes header, no check needed. |