How to Add Mermaid Diagrams to Jira Issues (With 5 Examples)

Jira is where the work is described, but it's rarely where the diagrams live. They end up as screenshots pasted from a whiteboard tool, out of date the day after they're attached, and impossible to edit without the original file. Mermaid fixes that: the diagram is plain text inside the issue, so anyone who can edit the issue can update the diagram.

This guide covers how to get Mermaid rendering in Jira Cloud, then five diagrams that are worth adding to real tickets, each ready to copy.

Does Jira support Mermaid natively?

No. Jira Cloud's editor has code blocks, but it shows Mermaid source as plain text. To render it as a diagram you need an app. Mermaid Diagrams for Jira detects Mermaid in issue descriptions and comments and renders it in the browser, so the diagram source never leaves Atlassian.

Adding a diagram, step by step

1. Open an issue and edit the description, or start a new comment.
2. Insert a code block. Typing ``` in the Jira editor creates one.
3. Paste or write your Mermaid source. You don't need to pick a language from the code block menu (Jira doesn't list Mermaid); the app recognizes the diagram from its first line, such as flowchart or sequenceDiagram.
4. Save. The diagram renders in a panel on the issue and updates whenever you edit it.

From there you can open it full screen, switch between the rendered view and the source, or export it as SVG or PNG for a slide deck.

1. Bug reproduction: a sequence diagram

“Steps to reproduce” written as prose are easy to misread. A sequence diagram shows exactly which call fails and in what order, which is what the person fixing it actually needs.

sequenceDiagram
    participant U as User
    participant W as Web app
    participant A as Auth service
    U->>W: Click "Sign in with SSO"
    W->>A: Redirect with state token
    A-->>W: Callback with code
    W->>A: Exchange code for session
    A-->>W: 400 invalid_grant
    W-->>U: Blank screen (no error shown)

2. Workflow changes: a state diagram

Proposing a change to a Jira workflow? Draw the new states and transitions in the ticket so reviewers can see the whole thing before an admin touches the configuration.

stateDiagram-v2
    [*] --> Triage
    Triage --> Backlog: accepted
    Triage --> Closed: won't do
    Backlog --> InProgress: started
    InProgress --> Review: PR opened
    Review --> InProgress: changes requested
    Review --> Done: merged
    Done --> [*]

3. Epic scope: a flowchart of dependencies

On an epic, a small flowchart of which pieces depend on which makes the build order obvious and helps spot the work that can run in parallel.

flowchart LR
    A[Schema migration] --> B[API endpoints]
    A --> C[Backfill job]
    B --> D[Web UI]
    B --> E[Mobile UI]
    C --> F[Remove legacy table]
    D --> G[Launch]
    E --> G

4. Data model changes: an ER diagram

For stories that touch the database, an ER diagram in the description gives reviewers the before and after without opening a separate design doc.

erDiagram
    ACCOUNT ||--o{ PROJECT : owns
    PROJECT ||--o{ ISSUE : contains
    ISSUE ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes

5. Incident timeline: a timeline diagram

In a post-incident ticket, a timeline makes the sequence of detection, response, and recovery easy to scan.

timeline
    title Checkout outage
    T+0 min : Error rate alert fires
    T+7 min : On-call acknowledges
    T+19 min : Bad deploy identified
    T+24 min : Rollback started
    T+36 min : Error rate back to normal

Tips for diagrams that stay useful

• Keep it small. A diagram with eight nodes gets read. A diagram with eighty gets skipped. Split large diagrams by concern.
• Put it where the discussion is. A diagram in a comment is a proposal; once it's agreed, move it into the description so it's the first thing people see.
• Edit, don't replace. Because the diagram is text, Jira's history shows exactly what changed. That's something a pasted screenshot can never do.
• Prototype outside, paste inside. For bigger diagrams, iterate on mermaid.live and paste the finished source into the issue.

For the rest of the syntax, keep our Mermaid cheat sheet handy. If your team documents in Confluence too, Mermaid Macros for Confluence renders the same source on pages and in PDF exports.