Reference

The full syntax, colours, exports and limits of Mermaid Diagrams & Gantt for Confluence. It is written for people who already write Mermaid.

New to Mermaid? Start with the guide. Syntax not covered here is on mermaid.js.org.

This page uses Mermaid's word node (box) for a shape in a diagram. Every fact here is true of version 2.6.0.

On this page

• Kinds of diagram
• Flowchart
• Sequence diagram
• Entity relationship diagram
• Gantt chart
• Class diagram
• State diagram
• Pie chart
• Mind map
• Links
• Colours
• The editor
• Pasting
• The diagram on the page
• Exports
• What is stored
• Security
• What's new
• Still stuck?

Documentation for Mermaid Diagrams & Gantt Recurring Requests Issue Templates

Guide Diagram recipes Reference

The first line that is not blank sets the kind. Eight kinds have a button under Examples and a Syntax reference panel of their own.

Any first line the panel does not recognise shows the flowchart panel. Other kinds that Mermaid supports also draw; their syntax is on mermaid.js.org.

In the Syntax reference panel

The panel also has a Links group; see Links.

More

end is a reserved word, so a node cannot be called end. Use End or done.

Mermaid's page: Flowcharts. Recipe: Draw a process.

In the Syntax reference panel

More

Mermaid's page: Sequence diagrams. Recipe: Show who talks to whom.

In the Syntax reference panel

More

Mermaid's page: Entity relationship diagrams. Recipe: Document tables.

In the Syntax reference panel

More

A task's start is a date or after. Its end is a length, a date, or until.

A length is a number and a unit: ms, s, m, h, d, w, M or y. Lowercase m is minutes, and capital M is months.

A # or ; after a task's colon causes an error. Write dates the way dateFormat says.

Mermaid's page also lists topAxis. In the Mermaid this app includes, it causes an error, so leave it out.

Mermaid's page: Gantt diagrams. Recipe: Plan a project timeline.

In the Syntax reference panel

More

Mermaid's page: Class diagrams. There is no recipe for class diagrams; start from the Class example.

In the Syntax reference panel

More

Mermaid's page: State diagrams. Recipe: Show how statuses change.

In the Syntax reference panel

showData goes on the first line, after pie. It adds each value to the key, in square brackets. A title can also go on a line of its own, as title Tickets by channel.

Mermaid's page: Pie charts. Recipe: Show shares of a whole.

In the Syntax reference panel

More

A node's level comes from its indentation, compared with the lines above it.

Mermaid's page: Mind maps. Recipe: Map ideas.

• Links are supported in flowcharts.
• Only http: and https: addresses are kept. Any other scheme, such as javascript:, is dropped.
• Links open through Confluence, not inside the diagram's frame. A full address to a page or work item on your site opened in a new tab, with no prompt, when tested on 2.5.0.
• A relative address is resolved against the frame's own address, on Atlassian's app host. So the panel's example click A "/wiki/spaces/DOCS" does not open your page. Confluence warns about an external page instead, so use full addresses.
• Hover text shows, but on a short diagram it can be cut off at the frame's bottom edge.
• A linked node gets role="link" and tabindex="0", with the name "Open linked page". It opens with Enter or Space.

Guide: Link a box to a page or work item.

A new diagram starts on Auto. Auto uses Confluence's light or dark mode, which Confluence passes to the app's frame. The computer's setting stands in only until Confluence answers, at most 1.5 seconds, or if that fails.

A theme set in the source wins over the Colours setting. It can be set in frontmatter, or in an init directive.

---
config:
  theme: forest
---
flowchart LR
  A[Draft] --> B[Published]

Panels

A diagram drawn darker or lighter than the page sits on a panel of the background it needs. The app reads this from the colours Mermaid drew the text and lines in, not from the theme's name. So Mermaid's other dark themes, and a base theme given dark colours, get a dark panel on a light page too. A light drawing on a dark page gets a light panel.

When the source sets no theme or colours of its own, Auto matches the page and needs no panel. In print, every dark diagram sits on its panel, since paper is light.

Styling nodes

style, classDef and class colour nodes, and linkStyle colours lines. These colours stay the same in every theme and mode.

Downloads and exports

• Image, PNG and SVG use the theme on screen. An Auto diagram on a dark page downloads dark.
• A PNG has a white background, or a dark grey one when the diagram is drawn dark, by the Colours setting or by a theme in its source. An SVG has no background.
• The picture saved for exports draws Auto as default. A fixed setting is kept. It goes on the background its colours need, as a PNG does.

The editor opens by itself when you insert a Mermaid Diagram. Later, it opens from Edit on the selected diagram. A click inside the diagram does not select it; see Change a diagram later.

• Layout. Source and preview sit side by side when the editor is at least 900 px wide, and stack below that.
• Preview. It redraws 250 ms after you stop typing.
• Source. Syntax highlighting, line numbers and wrapped lines. Ctrl+Z undoes and Ctrl+F opens find and replace; on a Mac, use Cmd. Tab and Shift+Tab indent and outdent the lines the selection touches, by two spaces. Esc, then Tab within two seconds, moves focus on. Ctrl+M (Shift+Alt+M on a Mac) switches Tab between indenting and moving focus until pressed again. The hint beside Diagram source shows the first two.
• Examples. They stay available the whole time. If the source has text, a bar asks "Replace your diagram with the … example?" with Replace and Keep mine.
• Syntax reference. It follows the first line of the source. It opens by itself when the diagram is empty.
• Alt text for screen readers. Up to 250 characters.
• Action row. Save, Revert changes, Restore a previous version…, Cancel and Full documentation stay at the foot of the editor, however far it scrolls.

Draft with AI and Fix with AI

• Draft with AI is a closed section between Examples and the source. It holds a request box, "What should the diagram show?", of up to 2,000 characters; Diagram type (Let the AI choose, or one of the eight example kinds); and Copy prompt.
• While the editor holds a diagram, it offers Change my diagram, which puts the source in the prompt and asks "What should change?", and Start a new one, which leaves it out. An untouched example starts a new one until you choose.
• Copy prompt is off until the box has text, with a line saying why. After a copy, Show prompt shows the exact text copied. If the browser refuses to copy, the prompt is shown selected for Ctrl+C.
• Fix with AI appears under a parse or drawing error. It copies the source and Mermaid's error as one prompt.
• Both prompts ask for exactly one ```mermaid block in the Mermaid version the app draws with, with no init directive, theme or front matter, and nothing the strict security level refuses. The paste clean-up keeps just that block.
• A prompt holds the request, the source and the error. It holds nothing else from the page: not the alt text, the page or the versions. The app sends nothing to any AI.

Status line

Save is off while there is a parse or drawing error. It stays on while the source is empty, and an empty diagram shows "No diagram yet" on the page.

Save checks the text as it is at the click. It waits for a preview still running, and checks the text itself when the preview has not caught up. Text that does not draw is not saved: the error shows under the source, with Fix with AI, and scrolls into view. While Save is off it stays in the tab order, described by the status line.

Saving without a picture

When a diagram gets no picture for exports, Save does not close the editor. A note above Save reads "Not saved yet: no picture for Word and PDF.", then why: "This diagram is too large or too slow to draw as a picture." or "Confluence did not accept this diagram with its picture." Focus moves to the note.

Save without picture saves the diagram with no picture, for the text and Colours the note was about. An edit or a new Colours choice takes the note away, and Save tries the picture again.

Versions

• A save records the previous text as a version when the text changed and was not empty. Up to five are kept, newest first.
• Each version holds the text and the time, nothing else.
• Restore a previous version… appears once there is one. Each entry reads "age — first line", with the first line cut at 32 characters.
• Ages read "just now", "N min ago", "N h ago" or "N d ago".
• Choosing an entry loads its text into the editor. Nothing changes on the page until Save.

Other controls

• Revert changes restores the text the editor opened with. It is off while the text is unchanged.
• Cancel closes without saving. On a diagram that was just inserted, it removes the diagram.
• Full documentation opens mermaid.js.org/intro/syntax-reference.html through Confluence. Before version 2.5.0, the link did not open.

A paste is cleaned up when it holds wrapping that is never valid Mermaid. Everything runs in the browser.

• Two or more mermaid blocks are left as pasted. A fence without its closing line counts only when it is tagged mermaid.
• Plain Mermaid goes in unchanged. So does a paste into several selections, or during text composition in an input method.
• The note reads "Cleaned up the pasted diagram: … Undo restores it as pasted." It shows for 8 seconds, or until the next edit.
• The clean-up is its own undo step. The first Ctrl+Z gives back the raw paste, and the second removes the paste.
• A diagram that opens as that JSON is unwrapped the same way. The note reads "Cleaned up this diagram: … Save to keep it." Undo or Revert changes brings back what was saved.

Guide: Paste from GitHub or another app and Moving a diagram from another Mermaid app.

• The toolbar shows on hover or keyboard focus. On touch screens it always shows. The zoom level sits between − and +.
• Zoom runs from 25% to 400%. Ctrl or Cmd with the wheel zooms too.
• The diagram starts fitted to the width. It fits again when the width changes, until the reader zooms.
• PNG and Image are drawn at twice the diagram's natural size. Downloads are drawn again without HTML labels, so text can wrap a little differently.
• The diagram has role="img", named by its alt text, or "Mermaid diagram" without one. Print hides the toolbar.

Messages

Under the licence message, the page says: "Your diagram is safe — it is stored on this page and will render again as soon as Mermaid Diagrams & Gantt for Confluence has an active licence."

The alt text paragraph appears only when the diagram has alt text. The picture's own alt text is the diagram's alt text, or "Mermaid diagram". An empty diagram exports as "Mermaid diagram (empty)", except in PDF.

The saved picture

• It is drawn when you select Save. Auto is drawn as default, on the background its colours need (see Colours).
• It is shown at its natural size, up to 680 px wide, centred.
• It is drawn at 2 pixels per CSS pixel. It steps down to 1.5, 1 and 0.75 until it fits about 73 kB. It is an indexed-colour PNG of up to 256 colours, with the diagram's main colours kept exact. That makes it about 40% smaller than before 2.6, so most large diagrams keep 2 or 1.5. A browser that cannot make one saves an ordinary PNG.
• It is skipped when the source is over 50,000 characters, or the preview took over 1.5 seconds. It is also skipped when it would be taller than 2,112 CSS px where it is shown (22 inches, the tallest picture Word holds), takes over 5 seconds, or does not fit. Then Save asks first; see Saving without a picture.
• A save that changes neither source nor Colours reuses it, unless it was saved before 2.6 in full colour. That one is drawn again, and kept if the new drawing fails. Exports use a picture only while it still matches both. For a source that sets its own theme or colours, a picture saved before 2.6 no longer matches: it exports as code until the diagram is saved again, and page versions from before that save keep the code.
• If Confluence refuses the save with the picture, the editor asks first, as for a diagram with no picture.
• Diagrams saved before version 2.4 have none until they are opened and saved.

The export function

Confluence calls the app's own function on Atlassian's platform for every diagram in an export. It receives the diagram's saved settings and returns a picture or text.

It keeps nothing, makes no network calls and logs only an error's name. Each diagram is one call per export.

CONFCLOUD-82734 reports that pages with about 100 or more such macros can reach Atlassian's call limit. Some diagrams are then missing from the export.

Each diagram's saved settings are the macro's configuration. They live in the page body and in each page version.

Each picture is up to about 73 kB, so 30 diagrams at the cap add about 3 MB to a page. The app uses no Forge storage, and Eriksen Labs holds no copy.

• The app requests no permission scopes and declares no egress.
• Mermaid runs at securityLevel: 'strict', which the app never relaxes. Labels are sanitised.
• Links are http and https only, and open through Confluence.
• Paste clean-up runs in the browser.
• The export function keeps nothing, makes no network calls and logs only an error's name; see Exports.
• Draft with AI and Fix with AI copy a prompt to the clipboard. The app sends nothing to any AI.

Read our security policy and privacy policy.

2.6.0

• Draft with AI, above the source, copies a prompt for the AI chat you use. Fix with AI, under a parse or drawing error, copies the diagram and the error. The app sends nothing to any AI.
• Save, Revert changes and Cancel stay at the foot of the editor.
• Tab and Shift+Tab indent and outdent the source. Esc, then Tab, moves on.
• Save checks the text as it is at the click, and refuses text that does not draw.
• A diagram with no picture for exports is saved only after Save without picture.
• A Save selected before the diagram has loaded saves nothing. Before, it could store an empty diagram.
• The saved picture is indexed colour, about 40% smaller, so large diagrams keep a sharp one.
• Panels, downloads, prints and saved pictures go on the background the drawing's own colours need. A diagram saved before 2.6 whose source sets a theme or colours needs one more save. Until then, Word shows its source as code, and PDF draws it live.

2.5.0

• A dark diagram on a light page, or a light one on a dark page, sits on its own panel.
• Auto follows Confluence's light or dark mode, not the computer's.
• Paste clean-up removes Markdown fences, AI chat wrapping and other Mermaid apps' wrapping. Undo restores the raw paste, and a note says what was removed.
• The editor's Full documentation link opens.

2.4.0

• PDF export without the diagram toolbar.
• A wider editor, with source and preview side by side.
• Saving a diagram stores a picture of it for Word and PDF exports.
• Diagrams saved before 2.4 need one open and save. Until then, Word shows their source as code. PDF draws them live, which is slower, and a page with many of them can fail.
• A very large diagram may be saved without a picture. Word then shows its source as code.
• The export function, which runs on Atlassian's platform when Confluence exports a page, shows page history or emails watchers. See Exports.

Raise a request in our support portal, or email [email protected]. First reply in 1-3 business days, depending on severity (see our service level agreement).

Include the diagram's source (select Copy in its toolbar), what you expected and what happened.