Mermaid+ Diagrams for Jira — User Guide

Overview

Mermaid+ Diagrams for Jira lets you create beautiful diagrams directly on Jira issues using Mermaid syntax. Choose from 26 diagram types, customize colors and fonts, and preview your diagram live before saving. Each diagram is stored on the issue and visible to everyone who can view it.

Getting Started

Adding a Diagram to an Issue

1. Open any Jira issue
2. Find the Mermaid+ Diagrams panel above the Activity section and click the panel icon to add it
3. Click the + (Create Diagram) button in the top-right of the panel
4. The editor opens in a fullscreen modal with a three-column layout:
   • Left: Live Preview
   • Middle: Quick Templates
   • Right: Settings + Code Editor
5. Write or paste your Mermaid code in the editor
6. Click Save — the diagram is stored on the issue and displayed in the panel

Editing an Existing Diagram

Click the ✏️ (Edit Diagram) button in the top-right of the panel to reopen the editor. All your settings and code are preserved.

Permissions

• View: Anyone who can view the issue can see the diagram
• Edit/Create: Only users with Edit Issues permission can create or modify diagrams

---

Editor

Live Preview

The left column renders your diagram in real-time as you type. Any changes to code or settings are reflected immediately.

Quick Templates

The middle column provides one-click templates for all 26 supported diagram types. Click any template to load its starter code into the editor.

Syntax Guide

Click the ? button in the header to open the full syntax reference. Browse 26 diagram types with descriptions and code examples. Hover over any code block and click the insert button to load it into the editor.

---

Settings

Font

• Family — Choose from Inter, Arial, Helvetica, Georgia, or Courier
• Size — 12px, 14px (default), 16px, 18px, 20px

Colors

Five customizable colors with visual color pickers:

Color	Affects
Node	Background color of diagram nodes/boxes
Text	Text color inside nodes
Border	Border color of nodes
Line	Edge/arrow line color
Bg	Diagram background color

Theme

Mermaid built-in themes:

Theme	Description
Default	Clean light theme with customizable colors
Dark	Dark background with high-contrast text
Forest	Green-tinted natural color palette
Neutral	Grayscale minimal theme

Note: The Default theme uses your custom color settings. Other themes apply their own color palette.

Output Size

Controls the displayed size of the diagram in the issue panel:

Size	Scale
Small	0.5x
Medium	1x (default)
Large	1.5x
X-Large	2x

---

Dark Mode Support

The diagram automatically adapts to Jira's dark/light mode:

• When you save a diagram, the current Jira theme is recorded
• When the issue loads, if the theme has changed, text and background colors are adjusted for readability
• The editor preview also adapts to dark mode

---

Supported Diagram Types

Flowchart

Directed graph diagrams with nodes, arrows, and subgraphs.

graph TD
    A[Start] -->|Yes| B[Process]
    B --> C{Decision}
    C -->|Option 1| D[Result 1]
    C -->|Option 2| E[Result 2]

Directions: TD (top-down), BT (bottom-up), LR (left-right), RL (right-left)

Node shapes: [Square], (Rounded), {Diamond}, ((Circle))

Sequence Diagram

Interaction diagrams showing messages between participants.

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob
    Bob-->>Alice: Hi Alice

Class Diagram

Object-oriented class relationships with inheritance, composition, and visibility.

classDiagram
    Animal <|-- Duck
    Animal : +int age
    class Duck {
        +String beakColor
        +swim()
    }

State Diagram

Finite state machines with transitions between states.

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing
    Processing --> Done
    Done --> [*]

Entity Relationship Diagram

Database schema diagrams with entity relationships.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains

User Journey

Task satisfaction maps with sentiment scores (1–5).

journey
    title My working day
    section Morning
      Make tea: 5: Me
      Do work: 3: Me

Gantt Chart

Project schedule charts with tasks, dependencies, and milestones.

gantt
    title Project Plan
    dateFormat YYYY-MM-DD
    section Phase 1
    Research :a1, 2024-01-01, 30d
    Design   :after a1, 20d

Pie Chart

Proportional data visualization.

pie title Time Allocation
    "Development" : 45
    "Testing" : 30
    "Meetings" : 25

Git Graph

Git branch and commit history visualization.

gitGraph
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop
    commit

Mindmap

Hierarchical tree diagrams for brainstorming.

mindmap
  root((Central Topic))
    Branch A
      Sub-topic 1
    Branch B
      Sub-topic 2

Timeline

Chronological event sequences.

timeline
  title History
  section 2020
    Event A : Description
  section 2021
    Event B : Description

Requirement Diagram

Requirements traceability diagrams linking requirements to elements.

requirementDiagram
    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }
    element test_entity {
    type: simulation
    }
    test_entity - satisfies -> test_req

C4 Diagram

Software architecture diagrams following the C4 model.

C4Context
    title System Context
    Person(user, "User")
    System(app, "Application")
    Rel(user, app, "Uses")

Quadrant Chart

Two-axis categorization charts.

quadrantChart
    title Analysis
    x-axis Low --> High
    y-axis Low --> High
    quadrant-1 Expand
    quadrant-2 Promote
    Item A: [0.3, 0.6]
    Item B: [0.7, 0.4]

Sankey Diagram

Flow diagrams showing quantities through a system.

sankey-beta
Source,Target,100
Source,Other,50

XY Chart

Bar and line charts.

xychart-beta
    title "Revenue"
    x-axis [Q1, Q2, Q3, Q4]
    y-axis "USD" 0 --> 100
    bar [30, 45, 60, 80]
    line [32, 48, 62, 78]

Block Diagram

Block diagrams with columns layout.

block-beta
  columns 1
  db(("DB"))
  block:ID
    A["Block A"]
    B["Block B"]
  end
  ID --> db

Packet Diagram

Network packet structure diagrams.

packet-beta
0-15: "Source Port"
16-31: "Destination Port"
32-63: "Sequence Number"

Kanban Board

Board-style task organization.

kanban
  To Do
    Task 1
  In Progress
    Task 2
  Done
    Task 3

Architecture Diagram

Infrastructure and service architecture.

architecture-beta
  group api(cloud)[API]
  service db(database)[Database] in api
  service server(server)[Server] in api
  db:L -- R:server

Radar Chart

Multi-axis comparison charts.

radar-beta
  axis Math, Science, English
  curve Alice{85, 90, 80}
  curve Bob{70, 75, 85}
  max 100

TreeView

File/folder tree visualization.

treeView-beta
  "root"
    "src"
      "index.ts"
    "test"
      "index.test.ts"

Treemap

Hierarchical data as nested rectangles.

treemap
  "Category A"
    "Item 1" : 10
    "Item 2" : 20

Ishikawa (Fishbone)

Cause-and-effect diagrams.

ishikawa
  Problem Statement
    Category A
      Cause 1
    Category B
      Cause 2

Venn Diagram

Set relationship diagrams.

venn-beta
  title "Team Skills"
  set Frontend
  set Backend
  union Frontend,Backend["Fullstack"]

ZenUML

Sequence diagrams using ZenUML syntax with participant types.

zenuml
    title Service Flow
    Actor User
    Database API
    User->API: Request
    API->User: Response

---

Tips

• Use the Syntax Guide (? button) to quickly find the right syntax for any diagram type
• Start with a Quick Template and modify it to fit your needs
• Use Dark or Forest themes for issues viewed in dark-themed Jira spaces
• Adjust Output Size to control how large the diagram appears in the panel
• All settings are preserved when you re-edit an existing diagram

---

Performance

Diagrams render instantly on issue load using cached SVG. The Mermaid.js library is only loaded during editing — not when viewing issues. This keeps your Jira issues fast.

---

Support

For issues or feature requests, please visit the app's listing on the Atlassian Marketplace.