Task: Add PlantUML recipe and extend codegen with puml scaffold

Table of Contents

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.org exists (org-roam ID, v2 frontmatter) and covers: prerequisites, writing .puml source, running plantuml to export PNG, embedding via #+attr_html: / #+attr_latex: / #+caption: in an org-mode file.
  • compass add diagram <slug> scaffolds <slug>.puml with the standard header; the skeleton compiles without errors under plantuml.
  • All existing .puml files 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.

Result

Emacs 29.1 (Org mode 9.6.6)