User manual · Version 2.1.0

Diagramaid user guide

Mermaid diagrams for Confluence Cloud, by KODICE.

Diagramaid adds a Mermaid diagram macro to Confluence. You write the diagram as text in a simple language called Mermaid, and the page shows it as a sharp, scalable picture. When something changes, you edit a few words instead of redrawing boxes and arrows.

This guide is for everyone who uses the app:

Prefer to watch first? See the Diagramaid video for a short tour of the app.

A Confluence page in light mode with an order diagram drawn by Diagramaid

#1. Before you start

  • Who can add diagrams: anyone who can edit a Confluence page. Readers only need permission to view the page.
  • Installation: a Confluence site administrator installs Diagramaid once for the whole site, from the Atlassian Marketplace. If you can't find the macro, ask your administrator.
  • Browser: any current version of Chrome, Edge, Firefox or Safari.
  • Mermaid knowledge: not required to get started. The editor has a ready-made example, and section 8 shows the most common diagram types.

#2. Add your first diagram

  1. Open a Confluence page and click Edit.
  2. Type /mermaid and pick Diagramaid - Mermaid for Confluence. You can also open Insert elements (the + in the toolbar) and look under Data & charts.
  3. The editor opens straight away. Write your Mermaid code on the left, or click Insert example to start from a sample.
  4. Check the preview in the centre.
  5. Click Save (or press Ctrl + Enter, ⌘ + Enter on a Mac).
  6. Publish or Update the page as usual.
The editor for a new macro: an empty code pane with "Insert example", and a preview that says "Your diagram appears here"

Tip: the diagram is saved with the macro, inside the page. Page history, copying a page, templates and permissions all work as they do for the rest of the page content.

Edit an existing diagram

While editing the page, select the diagram and click the pencil (Edit) icon in the macro's toolbar. The editor opens with the saved code and settings.

A macro without a diagram

If a macro is saved without any code, the page shows a placeholder until someone adds a diagram:

Placeholder on the page: "No diagram yet. Edit this macro (pencil icon) and write some Mermaid code to see your diagram here."

#3. The editor at a glance

The editor has three areas, all visible at once:

The Diagramaid editor with the Mermaid code on the left, the preview of an order diagram in the centre and the settings on the right
AreaWhat it's for
Code (left)The Mermaid code of your diagram, with line numbers and colours for keywords, arrows and text.
Preview (centre)Your diagram on a simulated Confluence page, updated as you type.
Settings (right)Presets and display options: theme, size, background, caption and the tools readers get.

The footer shows Unsaved changes while there are any, plus these buttons:

ButtonWhat it does
Reset settingsPuts all display settings back to their defaults. Your code is kept.
Cancel (Esc)Closes the editor without saving. If you changed something, it asks first.
Save (Ctrl/⌘ + Enter)Saves the code and settings in the macro and closes the editor. It reads Save anyway if the code has an error (see 4.3).
The "Discard unsaved changes?" dialog with the Keep editing and Discard buttons

The preview toolbar

The bar above the preview lets you check the diagram the way readers will see it. These options only affect the preview; they are not saved.

ControlWhat it does
☀ Light / ☾ DarkShows the preview on a light or a dark Confluence page. Readers can use either mode, so check both.
Fit pane / Fixed width / Full widthSimulates a page as wide as the preview, a standard fixed-width page (760 px) or a full-width page.
− 100% · Fit +Zooms the simulated page. Click the percentage to fit it to the preview again.
Focus (four-corner icon)Hides the code and settings so the preview fills the editor. Press Esc or click the icon again to leave focus mode.

The dimmed toolbar on the diagram shows which tools readers will get. It works on the published page, not in the preview.

Hide or show the settings

Click the panel icon at the top right of Settings to hide them and give the preview more room. Click Settings (or the panel icon at the edge) to show them again. In a narrow window the settings start hidden and open over the preview.

Keyboard shortcuts in the editor

ShortcutAction
Ctrl/⌘ + EnterSave
EscLeave focus mode; otherwise cancel (asks first if anything changed)
Ctrl/⌘ + FSearch (and replace) in the code
Ctrl/⌘ + Z / Ctrl/⌘ + Shift + ZUndo / redo
Tab / Shift + TabIndent / outdent the selected lines
Esc, then TabLeave the code editor with the keyboard

#4. Write and fix the code

4.1 Write code

Type in the code area; the preview follows a moment after you stop typing.

The two small buttons at the top right of the code area:

  • Copy copies all the code to the clipboard.
  • Paste pastes from the clipboard at the cursor. If your browser blocks it inside Confluence, press Ctrl + V (⌘ + V) instead.
The code pane with an ER diagram, line numbers and the Copy and Paste buttons

4.2 Find and fix errors

When Mermaid can't read your code, Diagramaid shows you where:

  • The line is underlined in red, with a red marker next to its number. Point at the marker to read the message.
  • Error on line N above the code jumps to that line.
  • The preview explains the error, with a Go to line N button. Full error message shows Mermaid's complete message.
A syntax error on line 7: the line is underlined in the code, and the preview says "Syntax error on line 7" with a Go to line 7 button

Common causes

ProblemExampleFix
Missing or misspelt diagram type on the first lineflowchar LRflowchart LR
Special characters in a labelA[Price (EUR)]Put the label in quotes: A["Price (EUR)"]
Two arrows in a rowA --> --> BA --> B
A bracket not closedA[Start --> BA[Start] --> B
Indentation in YAML (--- block)a config: key not indentedIndent the keys under config: with two spaces

4.3 Save work in progress

If the code still has an error, the button reads Save anyway. You can save and come back later: until the error is fixed, the page shows the error box instead of the diagram.

The error box readers see on the page while the code has a syntax error

#5. Change how the diagram looks

All display options are in the Settings panel. Each section shows its current value while it is closed (for example Fit width or Auto · Card). Point at an ⓘ icon for help on an option. Every change shows in the preview straight away and is stored when you click Save.

5.1 Presets

The three buttons at the top set several options in one click. Your code and caption stay as they are, and you can fine-tune everything afterwards.

PresetBest forWhat it sets
DocumentationEveryday pagesFollows Confluence light/dark mode, fits the page, all reader tools including View Mermaid code
PresentationPages you show on a screenColourful theme (Redux Color), Neo look, right-angle edges, a card frame, a tall fixed height, zoom and full screen only
MinimalClean pages, small diagramsNeutral theme, transparent background, no toolbar

The button of the active preset is highlighted.

5.2 Diagram style

Diagram style section: theme swatches, Look (Classic, Neo, Hand-drawn) and Edges (Curved, Right-angle)

Theme sets the colours. Each tile is a small sample of the real theme.

  • Auto (recommended) uses the Default theme on a light page and the Dark theme on a dark page, so the diagram always matches Confluence.
  • Light themes: Default, Neutral, Neo, Redux, Redux Color.
  • Dark themes: Dark, Neo Dark, Redux Dark, Redux Dark Color. They get a dark background so they stay readable on a light page.

Look sets the drawing style:

  • Classic: the standard Mermaid look.
  • Neo: softer, rounded shapes.
  • Hand-drawn: a sketchy, whiteboard style, good for drafts and ideas.

Edges sets how lines are drawn between shapes:

  • Curved: smooth curves (the standard layout).
  • Right-angle: straight lines with right-angle turns, often tidier for large diagrams.

Look and Edges work for flowcharts, state, class and ER diagrams. Other diagram types ignore them.

5.3 Size and position

Size and position section: Size (Fit width, Natural, Fixed height), the Height field and Alignment (Left, Center, Right)

Size

  • Fit width (default): wide diagrams shrink to fit the page width; small diagrams keep their natural size and are never blown up.
  • Natural: the diagram keeps its original size, even if it is wider than the page. Readers drag to see the rest.
  • Fixed height: the diagram is scaled to fit a box of the height you enter (120 to 2000 pixels). Useful for very tall diagrams, together with the zoom tools.

Alignment places the diagram on the left, in the center or on the right of the page.

5.4 Background and frame

Background and frame section: Background (Auto, None, Theme, Custom) and Frame (None, Border, Card)

Background

  • Auto (recommended): dark themes get a dark background; light themes get white when the reader uses Confluence in dark mode. Otherwise the page shows through. Diagrams stay readable in both modes.
  • None: always transparent, the page shows through. In the preview a transparent background is shown as a grey checkerboard.
  • Theme: always paints the theme's own colour (white or dark).
  • Custom: a colour you pick.

Frame

  • None: no frame.
  • Border: a thin line around the diagram.
  • Card: rounded corners and a soft shadow.

5.5 Caption and reader tools

Caption section with the caption text 'Order flow', and the Reader tools section with five switches

Caption is a short text shown under the diagram, for example Order flow. It is also used as the file name when readers download the diagram (order-flow.svg).

Reader tools choose what readers get on the diagram's toolbar:

SwitchGives readers
Zoom and panZoom buttons, Ctrl/⌘ + scroll, dragging
Open full screenThe full-screen viewer
Copy codeA button that copies the Mermaid code
Download SVG / PNGDownload buttons
View code sectionA collapsible View Mermaid code section under the diagram

Turn all of them off for a plain picture without a toolbar.

5.6 Settings in the code ("Set in code")

Diagram style section where Theme and Look carry a yellow 'Set in code' badge and are greyed out

Advanced users can put Mermaid's own settings at the top of the code, in a config: block between two --- lines:

---
config:
  theme: neutral
  look: handDrawn
  layout: elk
---
flowchart LR
    A --> B

Settings in the code always win. When the code sets the theme, look or layout (edges), the matching control in the Settings panel shows a yellow Set in code badge and is greyed out. Remove the line from the code to use the panel again.

%%{init: { "theme": "dark" }}%% directives at the top of the code work the same way.

#6. Read and use a diagram

On the page, point at a diagram to show its toolbar in the top-right corner. On a touch screen the toolbar is always visible. The author decides which buttons are shown (see 5.5).

A diagram on the page with the toolbar shown on hover, the caption "Order flow" and the open "View Mermaid code" section

The toolbar

The reader toolbar: zoom out, zoom in, reset zoom, copy code, download SVG, download PNG and open full screen
ButtonWhat it does
Zoom out / Zoom inZooms the diagram, from 20% to 800%.
Reset zoomBack to 100% and the original position.
Copy Mermaid codeCopies the diagram's code, e.g. to reuse it on another page.
SVGDownloads the diagram as an SVG file: a vector picture that stays sharp at any size, for documents, slides and wikis.
PNGDownloads the diagram as a PNG image, at twice the screen resolution for sharp text, for email and chat.
Open full screenOpens the diagram in a full-screen viewer.

A short message on the toolbar confirms actions such as Code copied, or says when the browser blocked one.

Zoom and pan with mouse, trackpad and keyboard

ToDo this
ZoomCtrl + scroll (⌘ + scroll on a Mac) or pinch on a trackpad. A plain scroll keeps scrolling the page.
Move around (pan)Drag the diagram. On a touch screen, drag with one finger once you have zoomed in.
ResetDouble-click the diagram.
With the keyboardPress Tab until the diagram is focused, then + / − to zoom, 0 to reset and the arrow keys to pan.

Full-screen viewer

Open full screen shows the diagram on its own, as large as your screen. There, the scroll wheel zooms directly, and the toolbar stays visible. Close the viewer with the × button or Esc.

The full-screen viewer: the order diagram fills the window, with the toolbar and a close button at the top right

View the code

If the author turned it on, View Mermaid code under the diagram opens the code. Select it to copy part of it.

#7. Light and dark mode

Diagramaid follows the reader's Confluence theme (light, dark or match browser). With the Auto theme and Auto background, the diagram switches with it, and changes as soon as a reader switches theme, without reloading the page.

The order diagram on a light Confluence page
Light mode
The same diagram on a dark Confluence page, with a dark theme and background
Dark mode

If you pick a fixed theme instead and keep the Auto background, Diagramaid keeps it readable: a dark theme gets a dark background on light pages, and a light theme gets a white background on dark pages. Use the ☀ Light / ☾ Dark switch in the preview to check both before you save.

The editor itself follows Confluence's mode too:

The Diagramaid editor in dark mode

#8. Mermaid quick reference

Diagramaid supports all Mermaid diagram types. The first line of the code names the type. A few common ones to get started:

Flowchart (process, decisions):

flowchart LR
    A[Order received] --> B{Payment OK?}
    B -- Yes --> C[Pack order]
    C --> D[Ship]
    B -- No --> E[Notify customer]

LR draws left to right; use TD for top to bottom. [ ] is a box, { } a decision, ( ) a rounded box and (( )) a circle.

Sequence diagram (who talks to whom):

sequenceDiagram
    Customer->>Shop: Place order
    Shop->>Payment: Charge card
    Payment-->>Shop: OK
    Shop-->>Customer: Confirmation

Entity relationship (ER) diagram (data models):

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

Gantt chart (plans and timelines):

gantt
    title Release plan
    dateFormat YYYY-MM-DD
    section Build
        Design      :a1, 2026-11-02, 4d
        Development :a2, after a1, 10d
    section Ship
        Testing     :a3, after a2, 5d
        Launch      :milestone, after a3, 0d

Also available: class, state, pie, mindmap, timeline, Git graph, quadrant, journey, block, packet, architecture and more. Several diagram types on one page, with different looks:

A Confluence page with a Gantt release plan and a hand-drawn flowchart

Full syntax for every type: Mermaid syntax reference.

Tip: comments start with %%, e.g. %% TODO: add the returns process. They don't appear in the diagram.

#9. Troubleshooting and FAQ

I can't find the macro when I type /mermaid.
The app isn't installed on your site, or not yet available to you. Ask your Confluence administrator.
The page shows "Syntax error on line N" instead of my diagram.
The code was saved with an error. Edit the macro, click Go to line N and fix the line (see 4.2).
The macro says "Diagramaid ran into a problem".
Something unexpected went wrong while showing the diagram. Reload the page. If it keeps happening, contact support (see section 10). The error is reported to KODICE automatically, without any page content.
A setting in the panel has no effect / is greyed out.
The code sets it in its config: block or an %%{init}%% line. Look for the Set in code badge and see 5.6.
Look or Edges don't change my diagram.
They only apply to flowcharts, state, class and ER diagrams.
The Paste button says it was blocked.
Your browser doesn't let the app read the clipboard inside Confluence. Press Ctrl + V (⌘ + V) instead.
"Copy was blocked by the browser" or a download does nothing.
The browser or your organisation's settings blocked it. For copying, use View Mermaid code and select the text. For downloads, try another browser, or the other format (SVG or PNG).
"Full screen is not available here".
Confluence didn't allow the full-screen viewer in this view. Use the zoom buttons on the page instead.
My diagram is too small to read.
Use Natural or Fixed height with a larger height (5.3), turn on Zoom and pan and Open full screen for readers, or split the diagram in two.
Icons (fa:fa-…) or images from the web don't show in my diagram.
Diagramaid never loads anything from the internet, for your security. Icon packs and external images are not supported; use text labels instead.
The diagram is missing when I export the page to PDF or Word.
Confluence doesn't include app macros like Diagramaid in PDF or Word exports. Download the diagram as PNG or SVG and insert the image, or share a link to the page.
My diagram looks slightly different after an app update.
Diagrams are drawn by the Mermaid version included in Diagramaid (currently 12.2.0). A newer Mermaid version can change spacing or details.
What happens if the app is uninstalled?
The code stays stored in the page, as part of the macro. Without the app, Confluence can't draw the diagram; it shows again once the app is reinstalled.

#10. Privacy and support

Your data stays in Confluence

  • The diagram code and settings are stored inside the Confluence page, like the rest of its content, with the same permissions and history.
  • Diagrams are drawn in your browser. The app has no server of its own, stores nothing outside the page and makes no calls to the internet.
  • Copy and download happen on your computer, only when you choose them.
  • When something in the app fails, a short technical error message is sent to KODICE through Atlassian's platform, so we can fix the problem. It never contains your diagram, page content or personal data. Your site administrator can turn this off.

Full details: privacy policy and security policy.

Get help

  • Email: write to support. We reply within 24 hours.
  • Tell us your Confluence site, the page (if you can share it), what you did, what you expected and what happened. A screenshot helps.
  • More: support page.

Diagramaid is made by KODICE. Mermaid is an open-source project not affiliated with KODICE or Atlassian. Confluence is a trademark of Atlassian.

Back to top ↑