Why We Built Yet Another Mermaid App for Confluence and Jira

[#1]

When I told my team "let's build a Mermaid app for Confluence," the first question was fair: there are already over a dozen Mermaid apps on the Atlassian Marketplace. Why build another one?

This is the story of how we found the answer — by reading user complaints, hitting the same walls ourselves, and making architectural decisions that, honestly, started as hacks but turned into the core of what makes Mermaid Plus different.

I'm Simon from NGPILOT, and this is the journey behind our Mermaid apps.

---

The State of Mermaid on Atlassian (It's Not Great)

Before writing a single line of code, we audited every Mermaid app we could find on the Marketplace. Here's the full picture:

Confluence Apps

App	Vendor	Framework	Live Preview	Templates	Diagram Types	Dark Mode	What's Actually Missing
Mermaid Diagrams for Confluence	Stratus Add-ons	Forge	No (Ctrl+Enter to render)	Yes (Complex to use)	Most types incl. beta, but no ZenUML	No (black & white only)	Old fullscreen Java-style UI; not native Confluence look; no auto-preview; no templates
Mermaid for Confluence	Tech Labs	Connect	Unknown	Unknown	Limited	Yes	Last updated Dec 2024 — likely abandoned
Mermaid Integration for Confluence	Toshihiro Sato	Connect	Yes	Yes (7 only)	Limited	Yes	Appears to be a clone of Tech Labs' app (same screenshots); last updated Dec 2024
Mermaid Charts & Diagrams	weweave	Connect	Yes (side-by-side)	Yes (per type)	24 listed	Yes (auto-adapt)	Connect framework (data may leave Atlassian); attachment-based macro variant
Mermaid Chart for Confluence	Mermaid Chart Inc. (Official)	Forge	Yes	Yes (20+)	Not fully listed	Not mentioned	2.6/5 rating; links to external mermaid.ai; account required for advanced features
Mermaid AI Diagrams for Confluence	XDevPod	Forge	Yes (split panel)	Yes (11+ samples)	11+ listed	Yes (20+ themes)	Confluence only; no per-diagram font/color customization; no built-in syntax guide
ContentCraft: Mermaid Diagrams	KaiserSoft	Forge	Not mentioned	Not mentioned	16 listed	Not mentioned	Stores diagrams as attachments; no live preview; no dark mode; no customization
Mermaid Diagrams & Charts	RVS	Forge	Yes (side-by-side)	Yes (15+)	12 listed	Not mentioned	No dark mode; no export; no customization; no Jira version
Mermaid Macro for Confluence	Chinese Technical Support	Forge	No	No	Not specified	No	Basic macro only — no editor beyond macro body text field
Mermaid Viewer for Confluence	Gluebin Softs	Forge	No	No	8+ listed	No	Basic viewer — insert macro, type code, saves; no editor features
CloudScript.io Mermaid	CloudScript.io	Connect	Unknown	Unknown	Unknown	Unknown	Legacy app, minimal recent updates
Mermaid Diagrams Viewer	Atlassian Labs	Forge	No	No	Unknown	No	Not an editor — just selects and renders existing code blocks already on the page; shows "Select codeblock with mermaid diagram to render"; unsupported

Jira Apps

App	Vendor	Framework	What It Actually Does
Mermaid Charts & Diagrams for Jira	weweave	Connect	Same editor as Confluence version, adapted for Jira
Mermaid for Jira	Mermaid Chart Inc. (Official)	Forge	Same as Confluence version, migrated to Forge
ContentCraft: Mermaid Diagrams for Jira	KaiserSoft	Forge	Archived — no longer available
Mermaid Diagrams for Jira	9ByNight	Forge	Auto-renders Mermaid code blocks in issue descriptions; has dark mode and SVG/PNG export; but no diagram editor — you write code in the description field, it renders in a panel

And then we read the community threads.

---

What Users Were Actually Saying

The complaints fell into clear patterns:

"It was working yesterday, now it's broken." Diagrams that render during editing but show as blank or raw code when anyone views the page. This came up in thread after thread — rendering works for admins but not regular users, works in edit mode but not view mode.

"Dark mode makes my diagrams unreadable." Mermaid generates diagrams with fixed fill colors. When Confluence switches to dark mode, light text on light backgrounds disappears. Some apps (like weweave's and XDevPod's) handle this through Mermaid's built-in theme system, but most others don't adapt at all — and even the ones that do rely on re-rendering the diagram with a dark theme rather than adapting the cached output.

"It just shows 'Error while loading diagram.'" The Atlassian Labs viewer — the free, official option — has community threads full of "Can't find code block to render automatically." It's unsupported, and it shows.

The official app from Mermaid Chart Inc. has a 2.6/5 rating. The company behind Mermaid.js itself — and users are still unhappy. That was the signal that this space needed a better option.

---

Building the Confluence Version: The Journey to Three Columns

We started with Confluence in February 2025.

One decision we made early: we would not use the Mermaid Live open-source project. Some vendors embed Mermaid Live directly, and you can tell — the UI looks like Mermaid's website, not like Confluence. The buttons, layout, and interaction patterns are Mermaid's design language, not Atlassian's. We wanted the editor to feel like it belongs in Confluence, not like a third-party tool was pasted in.

[Image: Mermaid Diagrams for Confluence — outdated classic UX]

[Image: Mermaid Integration for Confluence ]

So we built a Custom UI with a Monaco code editor, live preview, and quick-start templates. It worked, but v1 was a 2-column layout with some unresolved issues — ZenUML diagrams had layout problems, the preview wasn't always reliable, and the customization options were thin.

[Image: Mermaid Plus for Confluence — V1 2-column UX]

[Image: Mermaid Plus for Confluence — V2 3-column UX]

In April 2026, we did a thorough refactor. The new layout has three columns:

• Left (40%): Live preview — renders as you type, no manual trigger
• Middle (12%): Quick-start templates in a vertical list — one click inserts starter code for any of the 26 diagram types
• Right (48%): Settings panel on top (theme, size, alignment), Monaco code editor below

We also added a header with a built-in syntax guide (the ? button). It lists all 26 diagram types with code examples and hover-to-insert — because we kept forgetting Mermaid syntax ourselves, and figured our users would too.

The other core architecture decision: pre-render and cache the SVG. When you save a diagram, the app renders it immediately and stores the resulting SVG alongside the Mermaid source code. When anyone views the page later, we load only the cached SVG — the Mermaid.js library is never invoked. The read path is instant because it's just displaying an image, not running a diagram engine.

This also solved the "works in edit but not in view" problem that plagues other apps. Since the SVG is pre-rendered and stored as part of the macro's configuration, there's no runtime rendering step that can fail. What you see when you save is exactly what everyone else sees.

After the v2 refactor, we compared our feature set against every other Mermaid app on the Marketplace. This is the most feature-rich Mermaid editor available on the Atlassian Marketplace today — 26 diagram types with 26 one-click templates, live preview, Monaco editor, built-in syntax guide, dark mode adaptation, SVG caching, and full theme/size customization.

---

Building the Jira Version: The 32 KB Problem

In April 2026, we ported the app to Jira. The architecture was proven — same pre-rendered SVG approach, same live preview editor — but Jira introduced a constraint we didn't expect.

Jira issue properties have a 32 KB storage limit.

The Confluence version stores the SVG in macro configuration, which has no practical size limit. But Jira issue properties cap at 32 KB, and a rendered SVG for a complex architecture diagram can easily be 50-100 KB of raw XML.

This is where most Mermaid apps in Jira use attachments — they save the diagram as an attached file, which has no size limit. But attachments have their own problems:

• They appear in the attachment list, cluttering the issue
• They can be accidentally deleted during attachment cleanup
• They require separate permissions
• They add storage costs and API call overhead
• There's a sync issue — if the attachment upload fails, the diagram source exists but the image doesn't

We didn't want any of that. So we compressed the SVG instead.

compressSvg(svgString):
  1. Encode SVG string to bytes
  2. Gzip compress using native browser CompressionStream API
  3. Base64 encode for JSON storage
  4. Store with flag: svgEncoding: "gzip+base64"

The result: a 100 KB SVG compresses down to roughly 8-12 KB — well within the 32 KB limit. No attachments, no external calls, no sync issues. The diagram data lives in the issue property alongside the source code and configuration, as a single atomic write.

[Image: Mermaid Plus for Jira — 3-column editor with live preview]

On load, the app reads the property, checks svgEncoding, decompresses if needed, and displays the SVG. The Mermaid.js library only loads when someone opens the editor — never on a regular issue view.

The Jira version also needed the diagram to live on the issue itself, not as a separate page or external reference. We used a jira:issuePanel module, so the diagram appears as a collapsible panel right above the Activity section. It's visible to anyone who can view the issue, editable by anyone with edit permissions. No extra clicks, no context switching.

[Image: Mermaid Plus for Jira — diagram rendered on issue panel]

---

Dark Mode: The Problem Nobody Solved Well

Dark mode was the complaint that surprised us most. Here's why it's hard: Mermaid.js renders SVGs with explicit fill colors (fill="#FFFFFF", fill="#000000"). When Confluence or Jira switches to dark mode, those fixed colors don't adapt — you get white text on white backgrounds, or black text on dark surfaces.

Most apps either ignore dark mode entirely or re-render the diagram with a dark theme. Re-rendering means loading Mermaid.js again on every view — exactly the performance problem we were trying to avoid.

Our approach: adapt the cached SVG colors in place, without re-rendering.

When the app loads a cached SVG, it checks whether the current theme matches the theme that was active when the diagram was saved. If they differ, a adaptColors() function walks through the SVG and swaps specific color values:

• Dark fills (#000, #1a1a1a) → light gray (#dfdfde)
• White fills (#fff, #ffffff) → dark surface (#1D1D1D)
• Dark strokes → muted teal (#A6BFC6)

No Mermaid.js invocation. No re-rendering. The SVG is transformed in-place in milliseconds. And in the Jira editor, we also offer 4 theme presets (Default, Dark, Forest, Neutral) so users can choose the look before saving.

---

The Editor: Why Three Columns

Both apps share the same editor design — a 3-column layout that came from watching how people actually write Mermaid:

• Left (40%) — Live preview that updates on every keystroke. Not a "click to preview" button. Real-time.
• Middle (12%) — Template picker with one-click starter code for all 26 diagram types. For when you know you want a Gantt chart but don't remember the exact syntax.
• Right (48%) — Settings panel on top, Monaco code editor below. Monaco gives syntax highlighting and autocompletion for Mermaid, which makes editing much faster than a plain textarea.

[Image: Mermaid Plus for Confluence — editor showing dark mode diagram]

The editor also has a built-in syntax guide (the ? button) with code examples for every diagram type. Hover over any type to insert its template directly into the editor. We added this because we kept switching to the Mermaid docs while building our own diagrams — if we needed it, users would too.

---

What We Ended Up With

Two apps, built on Atlassian Forge, covering Confluence and Jira:

• 26 diagram types — every type Mermaid.js supports, including newer ones like architecture, treemap, radar, and Sankey
• 26 one-click templates — one per diagram type
• Live preview — renders as you type, no save-and-check workflow
• Pre-rendered SVG caching — Mermaid.js never loads on page/issue view
• Gzip compression (Jira) — fits complex diagrams within issue property limits, no attachments needed
• Dark mode adaptation — cached SVG colors are adjusted in-place without re-rendering
• Full customization (Jira) — fonts, 5 color pickers, 4 themes, 4 output sizes
• Forge-native — everything runs on Atlassian infrastructure, no external servers, no data leaves the ecosystem
• Free for teams up to 10 users

---

Try It

Mermaid Plus Diagrams for Confluence 

Mermaid Plus Diagrams for Jira

---

Quick Syntax Reference

If you're new to Mermaid, here are three starters:

Flowchart

flowchart TD
    A[Sprint Start] --> B{Stories Ready?}
    B -->|Yes| C[Start Development]
    B -->|No| D[Refine Backlog]
    C --> E[Code Review]
    E --> F{Approved?}
    F -->|Yes| G[Deploy]
    F -->|No| C

Sequence Diagram

sequenceDiagram
    participant Dev
    participant CI
    participant Staging
    participant Prod
    Dev->>CI: git push
    CI->>Staging: deploy (auto)
    Staging-->>Dev: smoke test results
    Dev->>Prod: promote to production

ER Diagram

erDiagram
    ISSUE ||--o{ COMMENT : has
    ISSUE ||--o{ ATTACHMENT : contains
    ISSUE }|--|| PROJECT : belongs_to
    PROJECT ||--o{ SPRINT : plans

---

What's Your Diagramming Workflow?

I'm genuinely curious — what tool do you use for diagrams in Confluence or Jira today? Have you hit any of the problems I described? Let me know in the comments.

— Simon from NGPILOT