Mermaid in Jira: 16 Apps Compared and 7 Tested Templates

A developer pastes a sequence diagram from a GitHub pull request into a Jira bug. On GitHub it was a diagram. In Jira it is a dozen lines of grey code, and the reviewer scrolls past it.

Jira Cloud has no Mermaid renderer. This guide gives you seven diagrams that work in any Jira Mermaid app, the errors people hit and their fixes, and the one question that decides which app to install: where it keeps your diagram.

What Jira does with a mermaid code block

Nothing. Atlassian’s editor supports markdown “to add headings, lists, code blocks, and more”, so ```mermaid becomes a code block, and a code block shows text.

That is the gap with the tools next to Jira. GitHub draws Mermaid in “GitHub Issues, GitHub Discussions, pull requests, wikis, and Markdown files”. GitLab’s Markdown docs say: “GitLab supports Mermaid version 11.” Atlassian’s own Bitbucket does not: BCLOUD-21675, “Implement Mermaid diagrams as part of Markdown”, has 310 votes and has been “Gathering Interest” since February 2022. We searched Atlassian’s public tracker for “mermaid” in the Jira, Jira Service Management and Confluence Cloud projects on 27 October 2026 and found no request to render it in Jira.

So every Mermaid diagram you see in a Jira issue is drawn by an app. The text you write is the same for all of them, which is why the templates come first.

Seven templates for Jira work, tested on Mermaid 11 and 12

Each template below is a job Jira teams do every week. We ran every one through the real Mermaid parser, versions 11.17.2 and 12.2.0, and all fourteen runs passed. Paste the text into your app’s editor, or into a description code block with the language mermaid if your app draws those.

1. A workflow, for the “how does this ticket move” question

stateDiagram-v2
    direction LR
    ToDo: To Do
    InProgress: In Progress
    InReview: In Review
    [*] --> ToDo
    ToDo --> InProgress: Start work
    InProgress --> InReview: Open pull request
    InReview --> InProgress: Changes requested
    InReview --> Done: Approved and merged
    Done --> [*]

State names cannot contain spaces, so give each one an id (InProgress) and a label (InProgress: In Progress). Use it on the epic that changes a workflow, before the Jira admin edits the real one.

2. A bug report that shows where the request died

sequenceDiagram
    actor User
    participant Web as Web app
    participant API as Orders API
    participant DB as Database
    User->>Web: Click "Pay"
    Web->>API: POST /orders
    API->>DB: INSERT order
    DB-->>API: Timeout after 30 s
    API-->>Web: 500 Internal Server Error
    Note over Web,API: Expected 201 Created

Solid arrows (->>) are calls, dashed ones (-->>) are answers. The Note is where you put the expected result, so the reader does not have to find it in the text.

3. A release plan that skips weekends

gantt
    title Release 4.2
    dateFormat YYYY-MM-DD
    excludes weekends
    section Build
    API changes        :a1, 2026-11-02, 5d
    UI changes         :a2, after a1, 4d
    section Release
    Code freeze        :milestone, m1, after a2, 0d
    Regression testing :t1, after a2, 3d
    Rollout            :after t1, 1d

after a1 chains tasks, so moving the first date moves the plan. excludes weekends keeps five-day tasks at five working days. Gantt text in a ticket is a sketch: the dates do not follow the Jira issues they describe.

4. An epic’s scope, including what is out

mindmap
  root((Checkout redesign))
    Payments
      Apple Pay
      Saved cards
    Cart
      Promo codes
    Out of scope
      Gift cards

Indentation is the structure. Tabs and spaces both worked in our test, but stay with one.

5. The architecture around a ticket

flowchart LR
    U([Customer]) --> W[Web app]
    W --> A[Orders API]
    A --> Q[(Queue)]
    Q --> P[Payment worker]
    P -->|PROJ-142: no retry| S{{Payment provider}}

Brackets choose the shape: ([ ]) stadium, [( )] database, {{ }} hexagon. A Jira key on an edge label points the reader at the ticket that changes that arrow.

6. An incident timeline for the post-mortem

timeline
    title Incident INC-311
    09.12 : Alert fires : Error rate 4%
    09.20 : On-call acknowledges
    09.41 : Roll back release 4.1.3
    10.05 : Error rate back to 0.1%

Write times as 09.12, not 09:12. The colon separates the time from the events, and 09:12 is a parse error (below).

7. The branches behind a fix

gitGraph
    commit id: "4.1.3"
    branch PROJ-142-retry
    checkout PROJ-142-retry
    commit id: "Add retry"
    commit id: "Tests"
    checkout main
    merge PROJ-142-retry tag: "4.1.4"
    commit id: "Next"

Branch names may contain the Jira key and hyphens. tag: marks the release that shipped the fix.

Seven errors you will hit, and the fix

We wrote each mistake into the parser on purpose. All of them fail the same way on Mermaid 11.17.2 and 12.2.0, and each fix passed on both.

These did not break anything in our test, so do not waste time on them: # in a label (Fix #42), %, curly quotes, <br> for a line break, and a Jira key such as PROJ-142 in a label or a branch name.

Mermaid 12 changed the picture, not the text

Mermaid 12.0.0 came out on 10 September 2026, and 12.2.0 on 13 October. The release notes are blunt: “This is a breaking release”. Two changes reach Jira:

• New layout and look. “Existing flowcharts, state and class diagrams will re-lay out and recolour.” ELK, a different layout engine, is now the default for flowchart, state, class, ER, requirement and use case diagrams. Mind maps keep their old layout.
• Newer browsers only. Mermaid 12 targets “ES2024, Safari 17.4+”. A colleague on an older Safari may see an error where everybody else sees a diagram.

Every Jira app bundles its own copy of Mermaid, so the version is the app’s choice. Three listings state one: Apportunity says Mermaid 12.1, NGPILOT’s Mermaid Plus says v12, and 9ByNight says 11.16. Our Mermaid Tabs runs 12.1.0, and our Excalidraw app 11.17. The others do not say. Mermaid Live, where many people draft, is built on 12.2 (its source asks for mermaid ^12.2.0). That is why a diagram drawn there can come out with different shapes, or not at all, in Jira.

Two things follow. A type that is new in 12, such as the use case diagram (usecase-beta), fails on Mermaid 11 with “No diagram type detected”. And if you want the same picture everywhere, put this front matter above the diagram. Mermaid 12’s notes name these three keys to keep the old look, and the block parsed on both versions in our test:

---
config:
  layout: dagre
  look: classic
  theme: default
---
flowchart LR
    A --> B

Where the diagram lives decides what you keep

Apps that look alike in a screenshot keep your diagram in very different places, and you find out which when you change apps. There are four.

1. In the issue’s own text. Apportunity, 9ByNight, Yamuno and Brutally Simple Inline say they draw ```mermaid blocks found in descriptions and comments. The diagram is ordinary Jira text: it is in the issue history, it moves with the issue, and it stays if the app goes. One vendor puts it plainly: “Uninstall the app and the text stays.” The price is that the source sits in the middle of the description, and every reader without the app sees code.

2. As a file on the issue. weweave adds a diagram to the description “as attachment” in one click, NGPILOT’s Excalidraw saves “each diagram as an attachment on the issue”, and the official Mermaid Chart app adds diagrams that are “viewable as an attachment”. An attached image stays when the app goes, but check whether the app can still edit it from its source.

3. In the app’s storage. Panel and tab apps keep diagrams in their own storage, which is what lets them show several per issue, or diagrams on a project page. On Forge that storage has a clock. Atlassian’s storage documentation says hosted storage “retains data for 28 days after uninstallation”, and a reinstall does not bring it back: the developer must get your consent and “submit a recovery request within 21 days of uninstallation”. Our own Mermaid Tabs and Excalidraw apps work this way. If a diagram matters, keep its source in a description too, or export it before you change apps.

4. Outside Jira. The official app “requires a Mermaid Chart account”: diagrams are made and stored there, and Jira shows them. Utoolity and Purple Rhapsody can load the source from a URL, such as a file in your Git repository. That is the right choice when the diagram’s real home is the repository, and a question for your security review when it is not: the source lives outside Atlassian.

All 16 Mermaid apps for Jira, side by side

We searched the Marketplace for “mermaid” in Jira Cloud on 27 October 2026 and kept every app that draws Mermaid: 16, two of them ours. Installs and prices come from the Marketplace API. “Listing says” means the vendor’s words; we did not install the other vendors’ apps.

Three things the table shows.

The most installed app is the one that takes your diagrams out of Jira. Mermaid Chart’s own app has 932 installs, the most of any, and a 2.4 rating from three reviews. It is free, but it is a window into a Mermaid Chart account: the right pick if your team already works there, and a second service to approve if not.

Most of the market is new and small. Ten of the 16 apps have fewer than 30 installs, and nine have no review yet. Ours are among them. Install counts tell you little here; a 15-minute trial on a real issue tells you more.

One app is frozen. Fulstech’s Mermaid for Jira Cloud is a Connect app last released in August 2020. Since March 2026 Connect apps can no longer be updated, and Connect support ends on 31 January 2027. Fulstech’s Markdown editor, a different app, is on Forge.

Which kind of app fits your team

• Your team already writes Mermaid in tickets (from GitHub, from an AI assistant, from Mermaid Live): an app that draws code blocks in descriptions and comments. Nothing to migrate, nothing lost if you switch.
• You want diagrams beside the ticket, several per issue, or on the project page: a panel or tab app. Our Mermaid Diagrams & Mind Maps in Tabs for Jira puts each diagram in its own tab on an issue or a project page, draws with Mermaid 12.1, and copies a whole tab set to another issue as a template. Each tab can also hold BPMN, Graphviz, LaTeX, Vega-Lite or WaveDrom. It does not draw code blocks in descriptions, and its tabs live in Forge storage, with the 28-day rule above.
• You want to sketch around the diagram: our Excalidraw Whiteboard & Mermaid Diagrams for Jira turns Mermaid text into Excalidraw shapes you can move, restyle and annotate, with the source still editable. It is a whiteboard first, so for a plain diagram a tab or code block app is quicker.
• The diagram’s real home is a repository or Mermaid Chart: an app that loads it from there.
• You need PlantUML, D2 or draw.io as well: one of the multi-format apps (Capable, Macro Pack, Visualize with Code) instead of one app per format.

Whatever you pick, test it with the seven templates above on a real issue during the trial, and open that issue on the oldest browser your team uses.

How we collected the data

• Which apps: Atlassian Marketplace REST API v2, addons?application=jira&hosting=cloud&text=mermaid, on 27 October 2026: 23 results. We kept the 16 that draw Mermaid and left out a report builder, a service desk app, our Portal Banners, and our other four Tabs apps, which draw Mermaid in any tab but are listed for BPMN, LaTeX, Graphviz and nomnoml.
• Installs, ratings, prices, framework, release: the API’s app record, versions/latest (release date, and the Forge app ID that Connect apps lack) and pricing/cloud/live (the monthly price for 10 users, and the per-user price of the 100-user tier). Discounts and annual prices are not included.
• Features and Mermaid versions: each vendor’s listing text, quoted. For our two apps, the version in our own source code.
• Templates and errors: Node.js with jsdom, mermaid.parse() from the npm packages [email protected] and [email protected]. Parsing checks the syntax, not the layout or colours.
• Native support and storage rules: Atlassian’s documentation and public tracker, GitHub’s and GitLab’s documentation, and Mermaid’s release notes, read on 27 October 2026 and linked above.

Prices and listings change. If you spot something out of date, tell us and we will fix it.