---
name: diagram-plantuml
description: Embed PlantUML diagrams inside a Confluence page using the {plantuml} macro in the storage body. Use when a page needs a sequence, component, class, state, activity, deployment, or timing diagram and the macro name is not in the caller's muscle memory.
---

# Diagram — PlantUML in Confluence

PlantUML renders server-side on the Confluence PlantUML plugin. The macro is
`{plantuml}`, the body is plain PlantUML between `@startuml` and `@enduml`,
and the host (BASS) renders it through the bundled plugin — no external URL
needed for private spaces.

## Hard rules

- **Macro name is `plantuml`**, lowercase. `{PlantUML}` and `{plantUml}` both
  fail to render.
- **Body goes inside `<ac:plain-text-body><![CDATA[ … ]]></ac:plain-text-body>`**,
  not inside `<ac:rich-text-body>`. The rich-text body treats the body as
  XHTML, which mangles `<`, `>`, and `&` that PlantUML relies on.
- **Always include `@startuml` and `@enduml`** even though PlantUML accepts
  bodies without them. The Confluence renderer is stricter than the CLI.
- **No diagram wider than ~900 px.** Confluence content columns are narrow;
  a wide diagram overflows on smaller screens. Split or simplify.
- **No diagram inside an info / note / warning panel.** The renderer nests
  and crops. Put the diagram at body root, then put a `{tip}` after it with
  the takeaway.
- **No diagram inside a code block.** Same nesting failure.
- **Never paste a base64 PNG into the body** to skip PlantUML. If PlantUML
  can't render what you drew, simplify the diagram.

## Storage template

```xml
<ac:structured-macro ac:name="plantuml">
  <ac:plain-text-body><![CDATA[@startuml
!theme plain
skinparam dpi 150

participant Client
participant Service

Client -> Service: request
Service --> Client: response
@enduml]]></ac:plain-text-body>
</ac:structured-macro>
```

The `!theme plain` directive keeps diagrams legible on the BASS light
background; the `skinparam dpi 150` is the right size for the Confluence
column width. Drop both when a diagram already has its own `skinparam`
block.

## Workflow

1. Decide the diagram type. See [references/diagram-types.md](references/diagram-types.md)
   for the cheat sheet (sequence, component, class, state, activity,
   deployment, timing, use case, ER, mindmap).
2. Draft the PlantUML in a `.puml` scratch file. Run `plantuml -tpng -checkonly
   -failfast2 file.puml` if `plantuml` is on `$PATH` — fast feedback loop
   before posting.
3. Wrap in the storage template above.
4. Add a one-line caption directly after the macro using a `{tip}` block or
   a bolded sentence; do not rely on the title attribute (some renderers
   strip it).
5. Hand the body to the `page-reviewer` skill. The reviewer re-runs the
   syntax check on every `{plantuml}` block.

## Common patterns

- **Sequence with notes:** use `note left of Alice: …` / `note right of
  Bob: …`. Inside an `alt`/`opt`/`loop` block, the note attaches to the
  branch.
- **Component / C4:** use `!include <C4_Container>` only if the BASS PlantUML
  plugin has the C4 stdlib. If unsure, prefer hand-drawn `component` arrows.
- **State:** use `state "Long label" as S1` to avoid breaking state names
  that contain spaces.
- **Timing:** use `robust` for digital signals and `analog` for continuous;
  mixing them on one line is a render error.

## Troubleshooting

| Symptom | Likely cause |
|---------|--------------|
| Macro renders as plain text | Macro name wrong, or the body is inside `<ac:rich-text-body>` instead of `<ac:plain-text-body>` |
| Diagram renders empty | `@startuml / @enduml missing, or body has unescaped < / >` outside CDATA |
| Diagram crops on the right | Width over the column budget — split or simplify |
| Theme reverts to dark on dark space | Use `!theme plain` explicitly; some renderers ignore the page theme |
| C4 include fails | Plugin doesn't ship the stdlib — switch to hand-drawn arrows |

Full troubleshooting table: [references/troubleshooting.md](references/troubleshooting.md).

## Related

| Skill | Role |
|-------|------|
| `confluence-page` | Owns the storage body; delegates diagrams here |
| `page-reviewer` | Re-runs the syntax check on every `{plantuml}` block |