Marcos Silva
67 lines
2.4 KiB
Markdown
67 lines
2.4 KiB
Markdown
# PlantUML Troubleshooting
|
|
|
|
Symptoms and fixes for the four classes of rendering failure on BASS
|
|
Confluence.
|
|
|
|
## Macro renders as plain text
|
|
|
|
| Cause | Fix |
|
|
|-------|-----|
|
|
| Macro name wrong (`PlantUML`, `Plantuml`) | Use `plantuml`, lowercase |
|
|
| Body inside `<ac:rich-text-body>` | Move to `<ac:plain-text-body>` |
|
|
| Macro opened but not closed | Add the matching `</ac:structured-macro>` |
|
|
| Page is in wiki renderer mode | Re-save in storage format (page properties → editor) |
|
|
|
|
## Diagram renders empty
|
|
|
|
| Cause | Fix |
|
|
|-------|-----|
|
|
| `@startuml` / `@enduml` missing | Add both, even if PlantUML accepts bodies without |
|
|
| Body has unescaped `<` / `>` outside CDATA | Wrap entire body in `<![CDATA[ … ]]>` |
|
|
| `!include` points to a stdlib the plugin doesn't ship | Replace with hand-drawn equivalent |
|
|
| File-size limit exceeded (very large diagrams) | Split into multiple diagrams |
|
|
|
|
## Diagram crops on the right
|
|
|
|
| Cause | Fix |
|
|
|-------|-----|
|
|
| Width > ~900 px | Split the diagram horizontally into two, or simplify |
|
|
| Long labels on long arrows | Shorten labels; move detail to body text |
|
|
| Padding parameters set too high | Drop `skinparam Padding`, `skinparam Margin` overrides |
|
|
|
|
## Theme reverts to dark on dark space
|
|
|
|
| Cause | Fix |
|
|
|-------|-----|
|
|
| Page theme overrides the diagram theme | Use `!theme plain` explicitly at the top of the body |
|
|
| BASS theme override | Hard-code colors with `skinparam` per element |
|
|
|
|
## C4 / standard library includes fail
|
|
|
|
| Cause | Fix |
|
|
|-------|-----|
|
|
| Plugin doesn't ship the stdlib | Switch to `component` diagram or hand-drawn boxes |
|
|
| Include URL is blocked by network policy | Mirror the stdlib locally, use `!include /path/to/C4_Container.puml` (only if the plugin supports it) |
|
|
|
|
## Debugging loop
|
|
|
|
1. Save the `.puml` body to a file.
|
|
2. Run `plantuml -tpng -checkonly -failfast2 file.puml`.
|
|
3. If local parse fails, the body is wrong — fix the syntax.
|
|
4. If local parse succeeds but Confluence fails, the wrapper is wrong — fix
|
|
the storage macro form.
|
|
|
|
## When to give up on PlantUML
|
|
|
|
- The diagram needs interactivity (hover, click). Confluence PlantUML does
|
|
not support this.
|
|
- The diagram needs real images (logos, photos). Drop them in via attachment
|
|
instead.
|
|
- The diagram needs to be edited by non-technical authors. PlantUML is not
|
|
the right tool.
|
|
|
|
## When to escalate
|
|
|
|
- The BASS plugin version changes and breaks a working diagram. Capture the
|
|
diff, fix the diagram, and update this troubleshooting page.
|