Eriksen Labs Support
Documentation

Mermaid reference: the diagram on the page

v2.10.0Updated

On this page
  1. Links
  2. Colours
  3. Look and layout
  4. The diagram on the page
  5. Exports
WriteMeaning
click A "https://…"Node A opens the address
click A "https://…" "Tooltip"The same, with hover text
  • 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.
A published flowchart with the pointer over the Build box and its hover text, Open the build work item, cut off at the bottom edge.
Hover text on a short diagram. It is cut off at the frame's bottom edge.

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

Colours

Colours settingSaved asDrawn with
Auto (match Confluence)autoMermaid's default theme on a light page, dark on a dark page. Under the Neo look: redux-color on a light page, redux-dark-color on a dark page
Defaultdefaultdefault
Neutralneutralneutral
Forestforestforest
Darkdarkdark

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.

Mermaid
---
config:
  theme: forest
---
flowchart LR
  A[Draft] --> B[Published]
A flowchart, Draft then Published, drawn in the Forest theme's green colors.
Drawn in forest, whatever the Colours setting says.

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 colors 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 colors, 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 colors 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 color nodes, and linkStyle colors lines. These colors 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 gray 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, or as redux-color under the Neo look. A fixed setting is kept. It goes on the background its colors need, as a PNG does.

Look and layout

Two settings beside Colours, new in version 2.9. The page, the preview, downloads and the picture saved for exports all draw with them.

SettingChoiceSaved asDraws
LookClassicNothing: it is the defaultAs every version before 2.9 drew
LookHand-drawnlook: handDrawnEvery shape as a sketch, at Classic's sizes, and the same way each time
LookNeolook: neoMermaid 12's own look, with its sizes
LayoutStandardNothing: it is the defaultMermaid's Dagre layout, as before 2.9
LayoutELKlayout: elkThe ELK layout engine, for flowcharts and class, state, ER and requirement diagrams
  • A diagram saved before 2.9 has neither key, so it is Classic and Standard and draws as before. A diagram left at both defaults stores neither key.
  • A kind of diagram that has only one look keeps it: a sequence diagram is never hand-drawn.
  • Layout arranges the five kinds in the table. Every other kind keeps its own layout: mind maps, swimlanes and architecture diagrams have engines of their own, and use case and agent flow diagrams are always drawn with ELK.
  • Under Neo, Colours on Auto is Neo's own palette (see Colours). Default, Neutral, Forest and Dark stay as they are under every look.
  • A look or layout set in the source's front matter wins over the setting, as a theme there does. A source that asks for ELK itself, with layout: elk, gets ELK; before 2.9 it was drawn with Dagre.
  • ELK is part of Mermaid 12. Its code, about 1.5 MB, is fetched from the app's own files only when a diagram uses it. It runs in the page, with no worker and no eval.
  • A hand-drawn picture for exports is heavier than a classic one. In our tests fewer diagrams kept the sharpest picture, and with ELK as well one got none. ELK also lays some diagrams out taller, which can take one past the height Word holds. When a diagram gets no picture, Save asks first (see Saving without a picture).
  • While the license is not active, both settings are off, like Colours.

Guide: Look and layout.

The diagram on the page

ButtonAccessible nameDoes
−Zoom outZooms out one step of 25%
+Zoom inZooms in one step of 25%
FitFit the whole diagram in viewShows the whole diagram: a wide one shrinks to the width, a small one stays at its own size. With Size on the page set to Fill the width, fills the width. In full screen, goes back to the screen's size.
⛶Full screenFull screen on or off. A double-click on the diagram, not on a link, does the same. If the browser refuses, the diagram expands in place.
CopyCopy diagram source textCopies the source
ImageCopy image to clipboardCopies a PNG
SVGDownload as SVGDownloads diagram.svg
PNGDownload as PNGDownloads diagram.png
  • 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 at its Size on the page. It is sized again when the width changes, until the reader zooms or selects Fit. A diagram wider than the page fades at the edge it continues past.
  • Full screen opens as large as the screen allows, with all of the diagram in view, but never below what fits its width at its own size: a long diagram scrolls down instead of shrinking. Leaving full screen goes back to the page's size.
  • 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.
  • Browsers: current Chrome, Edge and Firefox, and Safari 17.4 or later, which is what Mermaid 12 supports. A use case diagram uses a browser feature that arrived in Chrome and Edge 117, Firefox 119 and Safari 17.4; without it, the diagram shows "Could not render this diagram".

Messages

MessageWhen
"Loading diagram…"Before the diagram is drawn
"Image copied — paste it anywhere."After Image
"Diagram source copied."After Copy
"PNG downloaded." / "SVG downloaded."After PNG or SVG
"This browser cannot copy images."The browser has no image clipboard
"Clipboard blocked by the browser."Copy was refused
"No diagram yet", "Select this macro and choose Edit to write your Mermaid diagram."The saved source is empty. No toolbar.
"Something looks wrong on line N", or "This diagram could not be read", or "Could not render this diagram"The source cannot be drawn. Only Copy shows.
"Could not load the macro configuration"Confluence did not hand over the diagram. No toolbar.
"Could not load the diagram renderer"Mermaid failed to load

While the site's license is not active the page shows each diagram as it was last saved, with the toolbar; only the editor stops (see The editor). Before 2.8, the page showed "A licence is needed to show this diagram" in place of each diagram.

Exports

WhereEach diagram becomes
PDFThe saved picture. Without one, the live diagram without its toolbar, which is slower, and a page with many of them can fail.
WordThe saved picture. Without one, the alt text as a paragraph, then the source as a code block labeled mermaid.
Page historyThe saved picture, or the alt text and code block
REST export_viewAlways the alt text and code block, even with a saved picture: Confluence asks for it as an email export (measured 5 October 2026)
REST viewThe saved picture, or the alt text and code block
Notification emailAlways the alt text and code block
Include PageThe live diagram
Any other exportThe alt text and code block
Any export, license not activeThe same as with an active license (before 2.8: "A licence is needed to show this diagram.")

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, in the diagram's Look and Layout. Auto is drawn as default, or as redux-color under the Neo look, on the background its colors need (see Colours).
  • It is shown at its natural size, up to 680 px wide, centered.
  • 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-color PNG of up to 256 colors, with the diagram's main colors 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 the source nor Colours, Look or Layout reuses it, when the Mermaid now in the app drew it. A picture an earlier Mermaid drew, which is every picture saved before 2.9, is drawn again at the next save, and so is one saved before 2.6 in full color. The old picture is kept if the new drawing fails.
  • Exports use a picture only while it still matches the source and those three settings, whichever version drew it. So a picture saved by 2.4 to 2.8 keeps exporting as it was drawn, even where Mermaid 12 now draws the diagram a little differently on the page: open the diagram and select Save to bring the two in line. For a source that sets its own theme or colors, 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.