CloudScript Mermaid Diagrams for Confluence

CloudScript Mermaid Diagrams for Confluence lets you write Mermaid diagram code directly on a Confluence page and have it display as a diagram in place. It is a Confluence Cloud app built on Atlassian Forge. Each diagram is rendered in the browser when the page is viewed, by one of three engines: Mermaid 12, Mermaid 11 or Pele. A diagram drawn with Pele follows the reader's light or dark mode and can carry Confluence's colours or a theme of your own.

View on Marketplace

Adding a diagram

Edit a Confluence page, insert the Mermaid Diagram macro (type /Mermaid in the editor, or choose it from the macro list), then open the macro's configuration panel and enter your Mermaid code. Above the code you can give the diagram a title. Underneath it you choose which engine draws the diagram (Draw with), then that engine's own settings: Theme, Look and Layout for Mermaid 12 or Mermaid 11, or a Diagram colour and optional Pele CSS for Pele. A checkbox shows the diagram source beneath the diagram. Save the macro and publish the page, and the diagram is rendered when the page is viewed.

To show several diagrams on one page, add a separate Mermaid Diagram macro for each one. Each macro holds and renders its own diagram independently, with its own settings and its own engine.

Configuration options

The macro's configuration panel is laid out top to bottom: Diagram title, the diagram source, Draw with, the settings of the chosen engine, Show source below diagram, then Save and Cancel. The panel follows Confluence's light or dark mode.

Diagram title adds a heading above the diagram on your Confluence page. Leave it empty if you don't want one. The title is stored in the diagram's front matter as title:, so you can also set it in the code if you prefer.

The diagram source is the text box where you paste or write your Mermaid code (for example graph TD followed by your nodes and edges). A diagram copied out of a Markdown note with its code fence (a first line of ```mermaid and a last line of ```) works as pasted, because every engine ignores the fence.

Draw with chooses the engine that draws this diagram: Mermaid 12 (latest), Mermaid 11 or Pele. The bundled versions are shown beside it. See Supported engines below. Switching engine changes nothing in your code, so a diagram moved to Pele and back keeps every setting it had.

Mermaid settings

With Mermaid 12 or Mermaid 11 selected, Theme, Look and Layout are a visual editor for the diagram's front matter, which is the block of YAML settings between two --- lines at the top of a Mermaid diagram. Changing one of these controls writes the setting into the front matter in the source box, and editing the front matter by hand updates the controls, so the two always agree. Any other front matter settings or comments you have written yourself are left untouched.

• Theme controls the diagram's colours. The options are Automatic, Mermaid default, Neutral, Dark, Forest, Neo, Neo dark, Redux, Redux dark, Redux colour, Redux dark colour and Custom colours. Mermaid default is Mermaid's own theme named "default".
• Look controls the drawing style. The options are Automatic, Classic, Hand-drawn and Neo.
• Layout controls how nodes are arranged. The options are Automatic, Dagre and ELK.

Automatic means the setting is left out of the front matter, so Mermaid chooses whatever suits the diagram type. This matters most for Mermaid 12, where diagram types such as flowcharts and swimlanes bring their own theme and look.

Choosing the Custom colours theme reveals four colour settings (Fill, Border, Text and Lines), each with a colour picker and a box for a hex code. These apply only to this theme, and only to the Mermaid engines. Every theme and look is available with both Mermaid 11 and Mermaid 12.

If the source holds Pele settings (a Diagram colour or Pele CSS) while a Mermaid engine is selected, the panel notes that they do not apply to the Mermaid engines. Switch Draw with to Pele to use them.

Pele settings

With Pele selected, the panel shows Pele's settings in place of Theme, Look and Layout. Pele adapts the diagram to light and dark mode: colours from Confluence's palette adapt with it, and custom colours stay as written. See Colours on Pele below.

• Diagram colour tints every box in the diagram except those given their own colour in the code. Choose one of Confluence's colour families (Blue, Teal, Green, Lime, Yellow, Orange, Red, Magenta or Purple). White, the default, leaves the diagram in your site's own colours. Beside the menu, a Light mode and a Dark mode sample show how a box looks in each mode. The setting is written into the front matter as pele: color:.
• Pele CSS, the checkbox at the end of the Diagram colour row, gives the diagram a theme of its own in Pele's CSS variables. Tick it and a text box appears under the row. Paste or type a block such as the one under Pele CSS below. The CSS is written into the front matter as pele: css:, so you can also write it there. Untick the box to remove the theme from the diagram, or tick it again to put it back (Cancel discards every change as usual).
• If the code has fill or border colours that are not Confluence palette colours, the panel says how many and offers to review them. See Custom colours under Colours on Pele.
• If the code carries Mermaid theme settings (a themeVariables block or an %%{init}%% directive), the panel notes that Pele does not apply them. Choose a Diagram colour, or switch Draw with to Mermaid 12 to keep them.

Show source below diagram is a checkbox that, when ticked, prints the original Mermaid code in a panel underneath the rendered diagram. This is useful for documentation pages where readers may want to copy the source.

Supported engines

The app includes three rendering engines, chosen separately for each macro with the Draw with setting in its configuration panel:

• Mermaid 12 (12.1.0 at the time of writing), the default for new diagrams. It is the reference rendering of the Mermaid documentation, with every theme, look and layout.
• Mermaid 11 (11.15.0). Diagrams created before version 2.9 stay on Mermaid 11, so they look exactly as they did before that update.
• Pele (1.8.0), an open-source renderer published by Obsidian. It reads the same diagram syntax as Mermaid 12.1.0 and draws it in its own style, in your site's colours, which it follows into dark mode. See When to choose Pele below.

New diagrams use Mermaid 12. To move an existing diagram to another engine, open its configuration panel, change Draw with and save. You can change it back in the same way.

A page only loads the engines its diagrams use, so a page whose diagrams are all on one engine does not download the others.

Diagram syntax follows the specification for the engine you have chosen. The Mermaid documentation at mermaid.js.org is the authoritative reference for syntax, and Pele follows Mermaid 12.1.0. Pele's own documentation, including its theme variables, is at pele.run.

When to choose Pele

Pele draws every colour and font from CSS variables, where Mermaid writes its colours into the drawing. That difference gives a Pele diagram several advantages on a Confluence page:

• It follows your site's light and dark mode. A Mermaid diagram is drawn in fixed colours, so in Confluence's dark mode it stays on a white card. A Pele diagram takes its colours from the site's theme and switches with it as you read, with no reload: background, text, lines, node fills and chart colours all follow, and so does the source panel under it when Show source is on.
• It can be coloured with Confluence's own colours. Give the whole diagram a Diagram colour, or colour individual steps with Mermaid's colour statements. Palette colours switch to their dark-mode partners automatically.
• It can carry a theme of your own. Pele CSS sets the diagram's colours, font, corner radius and chart colours, for example in your brand's colours, with separate values for dark mode.
• Pasted diagrams keep their colours. A diagram copied from an Obsidian note or another Mermaid tool renders as pasted, with its colour statements drawn as written.

Pele does not do everything Mermaid does, so keep a diagram on Mermaid 12 when any of these matter:

• Themes, looks, layouts and custom colours. These are Mermaid features. With Pele selected the panel shows Pele's settings instead, and the diagram's colours come from the site theme, the Diagram colour and Pele CSS.
• Syntax newer than Mermaid 12.1.0. Pele follows that release. A diagram written for a later Mermaid may show a "Diagram error" on Pele. Switch the macro to Mermaid 12 or adjust the source.
• Icon packs. Architecture diagrams render with Pele's built-in icons (cloud, database, server, disk, internet). Icons from registered icon packs, such as logos:aws, are not available on Pele and show as their name.
• Node images. Pele does not draw images inside nodes. A node given an image (A@{ img: "…" }) appears without it. Mermaid 11 and 12 draw embedded images.

Every diagram type that Mermaid 12 renders, Pele renders too, including the types that are only in Mermaid 12 (swimlanes, use cases, Cynefin, railroad and agent-flow diagrams). Three types are drawn in a visibly different arrangement, not just different colours: C4 diagrams (each element as a labelled box rather than Mermaid's C4 shapes), mindmaps (an indented tree rather than a radial layout) and Ishikawa diagrams (a horizontal fishbone rather than Mermaid 12's vertical one). Journeys are drawn as a score chart, and Gantt charts have no "today" line. If the exact Mermaid arrangement matters for one of these, keep that diagram on Mermaid 12.

Colours on Pele

A Pele diagram can be coloured in two ways, and both follow the reader's light and dark mode.

One colour for the whole diagram. Choose a Diagram colour in the panel. Every box that has no colour of its own is tinted in that family, while lines, text and the background stay neutral. In code, it is the front matter

---
pele:
  color: blue
---

with one of blue, teal, green, lime, yellow, orange, red, magenta, purple or gray (colour is accepted too).

Colour for meaning. Use Mermaid's own colour statements, exactly as you would anywhere else: classDef with class or ::: for nodes and states, style for a single node or a subgraph, linkStyle for a path, and rect for the steps of a sequence diagram. A step with its own colour keeps it whatever the Diagram colour is. Here is a ready-made set of status colours to paste into a flowchart, using Confluence's own palette:

%% Status colours (Confluence palette; they switch with dark mode on Pele)
classDef todo     fill:#DDDEE1,stroke:#7D818A
classDef progress fill:#CFE1FD,stroke:#357DE8
classDef done     fill:#BAF3DB,stroke:#22A06B
classDef risk     fill:#F5E989,stroke:#B38600
classDef blocked  fill:#FFD5D2,stroke:#E2483D
%% Apply one with   C[Review]:::done   or   class A,B done

The same text draws with those colours in Obsidian or any other Mermaid tool, so the diagram stays portable. The block shows best on the White diagram colour: on a Blue diagram, a progress step is one shade from its neighbours. You can rename the classes or add more colours from the Confluence colour palette table below.

Dark mode. Any colour in the code that is one of Confluence's palette colours switches to its dark-mode partner when the reader uses dark mode, with no second set of colours to write. Any other colour stays exactly as you wrote it. The app keeps the text on it readable, draws a border or line that would vanish on the dark page in the neutral line colour, and fades a coloured sequence highlight so the messages over it stay readable. A custom colour therefore shows as a light area on the dark page, readable and unchanged.

Custom colours. A fill or border colour that is not one of Confluence's palette colours stays the same in dark mode, so it shows as a light patch on the dark page. When the code has one, the Pele settings show the warning "This diagram uses N custom colours that won't adapt to dark mode", with a Review link. Review lists each custom colour as written, where it is used (fill or border, and line number), and the nearest Confluence palette colour, previewed as it appears in light and in dark mode. Hover over a swatch to see its family, shade and hex value. Replace writes the nearest colour into every place that colour is used. This edits your diagram code, so Save keeps the change and Cancel discards it. Text colours, translucent colours and none are not listed: text follows the rules above, and a translucent colour blends with the page in both modes.

Confluence's colour palette. These are the colours Confluence uses in its own interface, taken from Atlassian's design system, and each one has a dark-mode partner designed to go with it. The app uses them in three places:

• the Diagram colour menu offers their colour families;
• Review suggests the nearest of them as a replacement for a custom colour;
• any of the values below written in your own colour statements switches to its dark-mode partner automatically.

Each family has a lightest and a light background, a bold background, a border colour and a text colour. The table gives the light-mode values, which are the ones to write in your code.

A bold background gets white text in light mode automatically. Leave color: out of the statement and the app picks the readable text colour.

Word export uses the light-mode colours: the image in the document is the diagram as read in light mode, with the Diagram colour, your colour statements and readable labels on dark fills.

Pele CSS

Pele draws every colour and font from a set of CSS variables, and lets you set them with a few lines of CSS (the full list is at pele.run/theming). The Pele CSS box takes that CSS as Pele's documentation writes it: a block that sets the variables, and a second block under @media (prefers-color-scheme: dark) for dark mode. This is how to give a diagram your brand's colours and font. For example, the Flexoki colours:

.pele {
  --pele-bg: #fffcf0;
  --pele-fg: #100f0f;
  --pele-muted: #6f6e69;
  --pele-line: #100f0f;
  --pele-surface: #f2f0e5;
  --pele-surface-alt: #e6e4d9;
  --pele-border: #cecdc3;
  --pele-accent: #205ea6;
  --pele-critical: #af3029;
}

@media (prefers-color-scheme: dark) {
  .pele {
    --pele-bg: #100f0f;
    --pele-fg: #cecdc3;
    --pele-muted: #878580;
    --pele-line: #cecdc3;
    --pele-surface: #1c1b1a;
    --pele-surface-alt: #282726;
    --pele-border: #403e3c;
    --pele-accent: #4385be;
    --pele-critical: #d14d41;
  }
}

In the diagram's front matter it is stored as

---
pele:
  css: |-
    .pele {
      --pele-bg: #fffcf0;
      ...
    }
---

What the app reads. Only Pele's own variables, set on the diagram as a whole (a rule for .pele, svg, :root or *). The first block is used in light mode, and the dark block when the reader's Confluence is in dark mode (the app maps the media query to Confluence's theme, not to the reader's operating system). A rule for part of a diagram, any other property, a variable Pele does not have, or a value the app cannot check (anything with url(), var() or calc(), for instance) is ignored, and the line under the box says what was read and what was not. CSS longer than 20,000 characters is not read at all. Variables you do not set keep the site's colours, or the Diagram colour's, so you can set one or two or the whole set.

A colour is a hex value (#fffcf0), rgb(), rgba(), hsl() or hsla(), a CSS colour name, transparent or currentColor. A font must be one the reader's machine has, or a generic family such as serif, because the app loads no fonts.

Charts. The series variables colour bar and line charts, pie slices, radar charts, Sankey flows and other colour-coded categories, and like every other variable they can have separate dark-mode values.

With the Diagram colour and coloured steps. A variable you set wins over the Diagram colour, and variables you leave out keep it. Steps coloured with Mermaid's classDef, style, linkStyle or rect keep their colours as written, and the app's dark-mode rules for them (readable labels, visible lines) stay as described under Colours on Pele. Those rules judge contrast against Confluence's colours, so with a dark theme of your own, check your coloured steps in both modes.

Dark mode. Without a dark block, your theme is used as written in both modes, like a custom colour. With one, the diagram switches to it with the page, with no reload.

Word export uses the light-mode theme: the image in the document is the diagram as read in light mode, in your colours and font. A font the export cannot find is drawn in the document's standard font.

Switching engines. Mermaid 12 and Mermaid 11 ignore the pele: block, so a diagram with Pele CSS still draws on them, in Mermaid's own colours.

Copying a diagram from Obsidian

A diagram copied from an Obsidian note renders as pasted, with its colours: classDef, style, linkStyle and sequence rect statements are all drawn as written, and a copied code fence is ignored. What to expect:

• Pele uses its own layout and style. Obsidian currently draws diagrams with Mermaid, so the Mermaid 12 engine here is the closer match for layout and proportions, and a diagram looks exactly as it did in Obsidian only once Obsidian itself draws with Pele.
• On Pele, parts of the diagram without a colour of their own take Confluence's colours, not the Obsidian theme's. A theme written in Pele's variables can be pasted into Pele CSS to set them.
• Mermaid theme variables and %%{init}%% theming are ignored by Pele and honoured by Mermaid 12. A diagram that relies on them should stay on Mermaid 12, and the panel says so when it sees them.
• Obsidian-only behaviour, such as internal links and CSS snippets, does not carry over.
• Colours outside Confluence's palette stay the same in dark mode, while palette colours switch.

Supported diagram types

Because the app passes your code straight to the rendering engine, it supports the full range of diagram types provided by the engine chosen for the macro. This includes flowcharts, sequence diagrams, class diagrams, state diagrams, entity-relationship (ER) diagrams, Gantt charts, pie charts, Git graphs, user-journey diagrams, mindmaps and timelines, among others. If a diagram type is valid in that version of Mermaid, it will render in the macro. Pele renders every type Mermaid 12 renders, with the differences in arrangement listed under When to choose Pele.

Some diagram types are only available in Mermaid 12 and Pele. Swimlane diagrams (swimlane-beta) are one example. If a diagram type from the current Mermaid documentation shows a "Diagram error" in an older macro, check that the macro's Draw with is set to Mermaid 12.

Layout engines (Dagre and ELK)

On the Mermaid engines, the Layout setting chooses how nodes are arranged. Dagre is Mermaid's standard layout. ELK is an alternative layout engine for flowcharts and other node-based diagrams, which often produces tidier routing and spacing on larger, more complex diagrams. Setting Layout writes the setting into the diagram's front matter, which you can also write by hand:

---
config:
  layout: elk
---
flowchart TD
  A --> B --> C
  A --> C

Both layouts are available with Mermaid 11 and Mermaid 12. Pele uses its own layout and ignores this setting. Swimlane diagrams only draw their lanes when Layout is set to Automatic, and the configuration panel shows a reminder if a swimlane diagram has another layout selected.

Exporting your page

Diagrams are included when you use Confluence's built-in Export to PDF, which uses Confluence's own capture of each diagram as it appears on the page, with no extra steps.

Diagrams are also included in Export to Word. Word export uses an image of the diagram that the app captures when the macro is saved, so a diagram looks the same in Word as on the page, and a diagram taller than a Word page is split across pages. Pele diagrams export in their light-mode colours. Macros created outside the editor, for example by a template or the REST API, or saved before Word export was available, export with a standard rendering of the same diagram until they are next saved from the editor.

Coming from the previous (Connect) version

If you used the earlier version of the app, diagrams you created previously continue to work; the macro reads the diagram code stored by the older version, so existing pages keep rendering without you needing to re-enter their source.

Troubleshooting

If a macro shows the message "No diagram yet", the macro has no source code saved, so open its configuration and add your Mermaid code.

If a macro shows a "Diagram error" message, the code contains a syntax error or uses a feature that the macro's engine does not support. Check the code against the Mermaid documentation, using the error text shown to find where the problem is, and check that Draw with is set to the engine the syntax belongs to.

If a diagram shows a "Diagram error" only on Pele, the source uses syntax that Pele (Mermaid 12.1.0) does not have. Switch the macro's Draw with to Mermaid 12, or rewrite that part of the diagram.

If the diagram error says "Node images must be inline data: URIs", a node image (A@{ img: "…" }) points at a web address. The macro never loads images from other locations, on any engine or in a Word export, so the diagram does not draw until the image is embedded as a data:image/png, gif, jpeg or webp URI. Mermaid 11 and 12 draw an embedded image. Pele does not draw node images, so on Pele the node appears without it.

A click link, or a link written in a label, works when it points at a web page (http or https), an email address (mailto) or a page on this site. Any other kind of link target is left out, and the node is not clickable.

If Diagram title and the engine's settings are greyed out, the front matter at the top of the diagram contains a YAML error. The configuration panel shows the error, and the settings become available again as soon as the front matter is corrected in the source box. The same error switches off the Pele CSS checkbox.

If the panel shows a Diagram colour instead of Theme, Look and Layout, the macro is on the Pele engine, which does not use them. Switch Draw with to Mermaid 12 or Mermaid 11 to see them.

If the Diagram colour menu shows a value it does not recognise, the front matter's pele: color: names something other than one of the colour families, and the diagram uses the site's colours until it is corrected.

If a coloured step looks the same as its neighbours on a coloured diagram, the step's colour and the Diagram colour are from the same family. Choose another Diagram colour, or White.

If a diagram with Pele CSS keeps the site's colours, open the macro and look at the line under the Pele CSS box, which says how many variables Pele reads and what it ignored. The usual causes are a rule for part of the diagram (.pele-node { … }, not read in this version), a value the app cannot check (var(--font-text) from an Obsidian theme, for instance), or a variable name Pele does not have.

If a swimlane diagram renders without its lanes, set Layout to Automatic.

For anything else, see the Support page.

Release history

• 23 Oct 2026 Mermaid Diagrams 2.13: Pele, diagrams that follow dark mode, and Word export Version 2.13
• 4 Oct 2026 Mermaid Diagrams 2.9: Mermaid 12 and a front matter editor Version 2.9
• 30 Jun 2026 Mermaid Diagrams 2.8: rebuilt on Atlassian Forge Version 2.8

Announcements for every app are on the News page.

Legal

Terms and privacy specific to this app:

• Terms of Service
• Privacy Policy

← Back to home