How to Add Mermaid Diagrams to Confluence and Jira

Confluence and Jira do not render Mermaid. Paste a flowchart into a Confluence code block and you get colored text. Paste it into a Jira description and you get monospaced text. Teams that keep architecture docs in Confluence and work in Jira run into this on day one.

There are three workable routes: a Marketplace macro, an exported image, or a share link with a preview card. Which one fits depends on whether you can install apps and how often the diagram changes. This post covers each route, then the pattern for keeping the source editable when the page only holds an image.

Route 1: A Mermaid macro from the Atlassian Marketplace

Several apps add a Mermaid macro to Confluence Cloud. The workflow is the same across them:

1. A site admin opens the Atlassian Marketplace, searches for "Mermaid", and installs an app that lists Confluence Cloud as supported.
2. In the page editor, type /mermaid (or open the Insert menu) and pick the macro.
3. Paste the Mermaid source into the macro body and publish.

The diagram renders on the published page and stays editable in place. Costs are per user and the app becomes a dependency: if it is removed, the macro body remains as text but the diagram disappears.

Two checks before you request an install. First, Data Center and Server sites need an app that explicitly supports Data Center; Cloud apps do not run there. Second, look at the app's Mermaid version in its release notes. Apps lag the current Mermaid release, so the newest diagram types may not render. The cheatsheet marks which types are long-established.

flowchart TD
    Start[Diagram needed on a Confluence page] --> Admin{Can you install Marketplace apps?}
    Admin -- Yes --> Macro[Install a Mermaid macro app]
    Admin -- No --> Image["Export PNG or SVG (MermanDraw)"]
    Macro --> Paste[Paste code into the macro]
    Image --> Attach[Attach image to the page]
    Attach --> Source[Keep code in an expand block]
    Paste --> Done[Page renders diagram]
    Source --> Done

Route 2: Export an image and attach it

Without an app, the image route works on every Confluence edition and every Jira project. Paste the Mermaid code into MermanDraw, pick a theme, and download PNG or SVG. Then drag the file onto the Confluence page or Jira issue.

• PNG is the default choice. It appears in page previews, PDF exports, email notifications, and the mobile apps. Export at 2× resolution so text stays sharp when the reader clicks to enlarge.
• SVG scales without blur and keeps file size small. Some Confluence sites restrict SVG attachments or show a download link instead of an inline preview. Test one page before standardizing on it.

Pick a theme that matches the page. The Clean or Paper themes blend into Confluence's white background; Dark or Neon stand out as a deliberate callout. Whatever you choose, use the same theme for every diagram in a space so the pages look like one set of documentation.

Route 3: Paste a share link

A MermanDraw share link carries a preview image, so when you paste it into a Confluence page or a Jira comment, the link card shows the diagram. This is the fastest route for a quick explanation in a comment thread, and the link opens the full-size diagram in a browser. Share links stay live as long as someone views them at least once every 180 days, so for permanent documentation pair the link with an attached PNG.

Mermaid in Jira issues

Jira has fewer options than Confluence. Issue descriptions and comments do not render Mermaid, and most Mermaid apps on the Marketplace target Confluence. The pattern that works on every Jira plan:

1. Attach diagram.png to the issue.
2. In the description, add a code block (the {code} macro in wiki markup, or the code block button in the new editor) and paste the Mermaid source into it.
3. Add the MermanDraw share link under the code block if the diagram is likely to change during the ticket.

The image gives reviewers the picture at a glance; the code block lets the next engineer update it without redrawing. Linked Confluence pages can reuse the same attachment.

sequenceDiagram
    participant D as Developer
    participant J as Jira issue
    participant C as Confluence page
    D->>J: Attach diagram.png
    D->>J: Add Mermaid source in a code block
    J-->>C: Link issue from release notes
    C->>C: Insert same image via attachment
    Note over J,C: One source, two renders

Keep the source next to the image

The failure mode of the image route is drift: someone updates the diagram in a local file, the page keeps the old PNG, and nobody knows where the source went. Avoid it with a fixed layout on every page:

• The image, full width.
• Directly beneath, an expand macro titled "Diagram source" containing a code block with the Mermaid text.
• Inside the expand, one line with the share link and the theme name so the next editor reproduces the same look.

Confluence indexes text inside expand macros, so the diagram's node labels become searchable, which an image alone never is. When the diagram changes, the editor opens the share link or pastes the code into the editor, exports a new PNG, and replaces the attachment. The flowchart and sequence diagram guides cover the syntax most architecture pages need, and the examples gallery has complete diagrams for deployment, API, and incident documentation to start from.

FAQ

Related

• Where does Mermaid render natively? — every tool that renders a mermaid block on its own.
• Export Mermaid to PNG and SVG — format choice and resolution.
• Mermaid diagrams in Notion