How to add Mermaid diagrams to Confluence Cloud (including diagrams from ChatGPT or Claude)

What Confluence Cloud does with Mermaid on its own

In our test on 27 October 2026, Confluence Cloud did not draw Mermaid on its own. Pasting Markdown into the Confluence editor converts headings, lists, tables, links and code blocks. A ```mermaid block becomes an ordinary code block with the Mermaid code as text. No diagram is drawn.

So the code arrives safely, but readers see the code. To see the diagram you need one of the options below.

Option 1: export an image from the Mermaid Live Editor

The Mermaid Live Editor at mermaid.live is a free online editor. Paste your code, check the diagram, download it as PNG or SVG, and upload the image to your Confluence page.

• It works today without installing anything in Confluence.
• The image goes stale. When the process changes, someone has to find the original code, edit it in the Live Editor, export again and replace the image.
• Nobody can edit the picture on the page. If the code was not saved with it, the next person has to redraw the diagram.

If you go this way, put the Mermaid code in a code block (or an expand) under the image, so the next person can redraw it.

Option 2: Atlassian Labs' Mermaid diagrams viewer

Atlassian Labs publishes a free app called Mermaid diagrams viewer. You put the Mermaid code in a normal Confluence code block, add the app's macro on the same page, and the macro draws the diagram from that code block. The app is open source (on GitHub).

This suits you if a code block plus a diagram that follows it is all you need.

Option 3: Mermaid Live Preview

Full disclosure: Dortus makes Mermaid Live Preview (on the Atlassian Marketplace). What it does:

• Code and preview side by side. The macro editor has the Mermaid code on the left and a live preview on the right that redraws while you type. If a line is wrong, the error shows the line and what Mermaid expected.
• Mermaid 12. Flowcharts, sequence, class, state, ER and Gantt diagrams, mindmaps, timelines and other Mermaid diagram types.
• Fits the page. On the page, a diagram fits the width. You can zoom in or open it large.
• Download when you need a picture. SVG or PNG, for a slide or an email.
• Version history. The last 20 saves of each diagram are kept, so a bad edit is not a lost diagram.
• Runs on Atlassian. The macro runs on Atlassian Forge. The code is saved in the macro on the page and the diagram is drawn in the browser of the person viewing it. No external account, and nothing is sent to Dortus.

Other Mermaid apps are on the Atlassian Marketplace as well. Points worth comparing: whether you see a preview while you edit, which Mermaid version it uses, and where the diagram is drawn (in the viewer's browser, or on the vendor's servers).

Step by step with Mermaid Live Preview

1. A Confluence admin installs Mermaid Live Preview from the Atlassian Marketplace.
2. Edit a Confluence page and type /mermaid. Choose Mermaid Live Preview.
3. Paste your Mermaid code on the left. The preview on the right shows the diagram.
4. Insert the macro and publish the page. To change the diagram later, edit the macro and change the code.

Asking ChatGPT or Claude for a diagram

AI assistants such as ChatGPT and Claude can write Mermaid code for you. Describe the process in plain words, say which diagram type you want, and ask for the code only. An example prompt:

Draw the approval process for a purchase request as a Mermaid flowchart.
An employee submits the request. The manager approves or rejects it.
Above 5,000 euros, finance must also approve. After approval,
purchasing places the order. Reply with only the Mermaid code.

The answer can look like this. You can copy it and paste it as it is:

flowchart TD
    A[Employee submits purchase request] --> B{Manager approves?}
    B -- No --> R[Request rejected]
    B -- Yes --> C{Amount above 5,000?}
    C -- No --> E[Purchasing places the order]
    C -- Yes --> D{Finance approves?}
    D -- Yes --> E
    D -- No --> R
    E --> F[Goods received]

Three things that save time:

• Leave out the fence lines. If the answer starts with ```mermaid and ends with ```, copy only the lines in between.
• Quote labels with brackets. A label such as A[Check stock (optional)] is a syntax error; A["Check stock (optional)"] works.
• Paste the error back. If Mermaid reports an error, give the error message to the assistant and ask for a corrected version.

For other diagram types, see 12 Mermaid diagram examples for Confluence.

Which option fits

One diagram that will never change: an image from the Mermaid Live Editor, with the code saved under it. A diagram next to a code block that readers may also want to see: Atlassian Labs' Mermaid diagrams viewer. Diagrams that people keep editing on the page, with a preview while they type: a macro such as Mermaid Live Preview.

Questions

Spotted something wrong on this page, or an option we missed? Email support@dortus.com.

See also: Mermaid diagram examples for Confluence: copy and paste