Documentation

Transom Diagrams

Set up the macro, write PlantUML or Mermaid, export to PDF and Word, and fix common problems.

Getting started

Install. A Confluence site admin installs Transom Diagrams from the Atlassian Marketplace and picks your Confluence Cloud site.
Insert the macro. Edit a page. Type /, then choose Transom Diagrams (or type /Transom).
Write. The editor opens full screen. Pick a starter template or paste your source. The preview updates as you type.
Save. Select Save, or press Ctrl+Enter (Cmd+Enter on Mac). The diagram shows on the page.
Publish. Publish the page as usual. Confluence needs a page title first. More.

To change a diagram later, select it on the page and choose Edit.

In the editor

The type toggle picks PlantUML or Mermaid. The editor detects the type from your source, so you rarely need it.
The template menu inserts a starter diagram.
Errors show the line number and a Go to line action.
If you leave with unsaved changes, the editor asks you to confirm.

On the page

Readers see a crisp SVG. The toolbar offers zoom, fit to page, copy source, and download as SVG or PNG.

PlantUML basics

PlantUML source starts with @startuml and ends with @enduml. The editor uses this to detect the type.

PlantUML

@startuml
title Sign in
actor User
participant App
participant API
User -> App : Open page
App -> API : GET /items
API --> App : 200 OK
App --> User : Render list
@enduml

Sequence, class and state diagrams all work. Use the templates to see the syntax.
skinparam settings work for colors and fonts.
Layout uses the built-in Smetana engine. A complex diagram can look a little different from one drawn with Graphviz on another server.
Not available: !include <...> standard-library files, includes from a URL, and !theme. The app makes no outside requests, so nothing can be fetched.

Full syntax: PlantUML language guide (external site).

Mermaid basics

The first line of Mermaid source names the diagram type, for example flowchart, sequenceDiagram, classDiagram, erDiagram, stateDiagram-v2 or gantt.

Mermaid

flowchart LR
  A([Request]) --> B{Authenticated?}
  B -- yes --> C[Load dashboard]
  B -- no --> D[Sign in]
  D --> B
  C --> E([Done])

Use flowchart TD for top-to-bottom and flowchart LR for left-to-right.
Text in square brackets is a box. Text in round brackets is a rounded box. Text in curly brackets is a decision.

Full syntax: Mermaid documentation (external site).

Templates

The template menu has 10 starters.

Engine	Templates
Mermaid	Flowchart, sequence diagram, class diagram, entity relationship, state diagram, Gantt chart
PlantUML	Sequence diagram, class diagram, state diagram, C4-style system context

The C4-style template uses plain PlantUML shapes. It does not use the C4 standard library, which would need an outside download.

Export to PDF and Word

Confluence cannot run apps while it builds a PDF or Word file. So Transom Diagrams prepares an image ahead of time.

When you select Save, the app renders your diagram to a PNG. The PNG is always light, on a white background.
The app attaches the PNG to the page as transom-diagram-<id>.png, as you.
When you export the page, Confluence puts that image where the diagram is.

Good to know. The export shows the diagram as it was at the last save. If you edit the source, save again.

You need permission to add attachments to the page. If the upload fails, the editor tells you. You can try again, or save without the image. Without the image, exports show your source as a code block.
Each new version of a diagram adds a new image. Older images stay in the page attachments. You can delete old ones. Keep the latest.
The PNG is kept to about 1.5 MB. The app scales it down if needed.

Limits

Item	Limit	Notes
Diagram source	100 KB	Counted in UTF-8 bytes (100,000). Text in some languages uses more than one byte per character. The editor shows the size and how much to remove. To go under the limit, split the diagram in two.
Export image	About 1.5 MB	The app scales the PNG down to fit. Very large diagrams can look small in a PDF. Split them for print.
Outside requests	None	Images, includes and themes from a URL do not load.
PlantUML	Smetana layout	No Graphviz. No standard library. No `!theme`.
Confluence	Cloud only	Not for Data Center or Server.
Browsers	Current Chrome, Firefox, Safari	Rendering runs in your browser.

Troubleshooting

"Publish needs a page title"

Confluence will not publish a page that has no title. Type a title at the top of the page, then select Publish again. Your diagram is not affected.

An error shows with a line number

The engine found a syntax problem. Select Go to line, then check that line for a typo, a missing keyword or a missing bracket. The preview comes back when the source is valid.

The diagram is missing or blank in a PDF or Word export

Open the diagram and select Save again. This makes a fresh export image.
Check that the page has a transom-diagram-…png attachment. If someone deleted it, saving again restores it.
Check that you can add attachments to the page. The editor shows a message if the upload fails.

PlantUML says it cannot include a file or theme

Standard-library includes (!include <C4/...>) and !theme are not available. Remove the line. Use plain shapes and skinparam instead.

The editor says the diagram is too large

The source limit is 100 KB. Split the diagram into two macros. Remove long comments or repeated blocks.

The preview is slow

The engine loads the first time you use it on a page. Large diagrams take longer. If it stays slow, split the diagram.

A PlantUML diagram looks different from another tool

Transom Diagrams uses the Smetana layout, not Graphviz. Boxes can sit in slightly different places. Add hidden links or direction hints (for example left to right direction) to guide the layout.

Still stuck?

Email [email protected]. Say which Confluence site and browser you use, what you did, and what you saw. Do not send private diagram source unless you are happy to share it. See support for response times.