Marcos Silva
98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
---
|
|
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 |
|