How to Create Mermaid Diagrams on Jira Issues (Step-by-Step Tutorial)

Jira issues are where your team tracks bugs, features, and tasks every day. But describing complex processes, API interactions, or system designs in plain text often leads to confusion and misalignment. Mermaid Plus Diagrams for Jira solves this by letting you create and embed Mermaid diagrams directly on any Jira issue, so the visual context lives exactly where the work happens. No external tools, no attached images that go stale, no switching between tabs.

In this tutorial, you will learn how to install the app, create your first diagram on a Jira issue, and use the right diagram types for common Jira workflows. Every Mermaid example in this guide is copy-paste ready, so you can drop it straight into your issues and see results immediately.

Why Add Diagrams to Jira Issues?

Jira tickets are the single source of truth for your team's work. When you attach a diagram to an issue, you give everyone who views that ticket an immediate visual understanding of what is happening. Here are the scenarios where diagrams on Jira issues make the biggest impact:

• Bug reproduction steps shown as a flowchart eliminate ambiguity about the exact path a user took to trigger the defect
• API flow documentation as sequence diagrams helps frontend and backend engineers agree on request and response patterns without leaving the ticket
• Design discussions illustrated with class diagrams or architecture diagrams keep technical conversations grounded in a shared visual model
• Sprint planning and grooming benefits from Gantt charts and timelines that show dependencies and critical paths right on the epic or story
• Incident post-mortems use fishbone (Ishikawa) diagrams to trace root causes directly on the incident ticket

Without embedded diagrams, teams resort to describing flows in bullet points, linking to external diagramming tools, or attaching screenshots that become outdated the moment the code changes. Mermaid diagrams on Jira issues stay current because they are text-based and can be edited in seconds.

What You Need Before You Start

• A Jira Cloud instance where you have permission to install apps (or ask your Jira admin to install the app)
• The Edit Issues permission on the project where you want to create diagrams (viewing diagrams only requires view permission on the issue)
• Basic familiarity with Mermaid syntax (this guide includes examples you can copy and modify, so no prior experience is strictly required)

Step-by-Step: Create Your First Diagram on a Jira Issue

Step 1 -- Install Mermaid Plus Diagrams for Jira

Head to the Atlassian Marketplace and search for Mermaid Plus Diagrams for Jira. Click Get App and follow the installation prompts. The app is available for Jira Cloud. Once installed, the Mermaid Plus Diagrams panel becomes available on every issue in your Jira instance.

If your organization requires admin approval for marketplace apps, send the app link to your Jira administrator and request installation. The process typically takes under a minute once approved.

Step 2 -- Open the Mermaid Panel on a Jira Issue

Navigate to any Jira issue where you want to add a diagram. Scroll to the area above the Activity section (comments, history, etc.) and look for the Mermaid+ Diagrams panel. Click the panel icon to activate it. If this is the first time you are using the panel on this issue, it will be empty.

The panel is issue-specific, meaning each Jira issue has its own diagram. This keeps the visual context tightly coupled to the work being tracked.

Step 3 -- Write Your Mermaid Diagram Code

Click the + (Create Diagram) button in the top-right corner of the panel. A fullscreen modal editor opens with a three-column layout:

• Left column: Live Preview -- your diagram renders in real time as you type
• Middle column: Quick Templates -- one-click starter code for all 26 supported diagram types
• Right column: Settings and Code Editor -- write your Mermaid code, adjust font, colors, theme, and output size

Start by clicking a Quick Template in the middle column if you want starter code, or type your Mermaid syntax directly into the code editor on the right. The live preview on the left updates instantly, so you can see the result of every edit without waiting.

Step 4 -- Preview and Customize Your Diagram

While you write or edit your code, the live preview on the left renders the diagram in real time. Use the settings panel to customize the appearance:

Font settings:

Setting	Options
Family	Inter, Arial, Helvetica, Georgia, Courier
Size	12px, 14px (default), 16px, 18px, 20px

Color settings:

Five customizable colors with visual color pickers let you match your company brand or improve readability:

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

Theme:

Choose from four Mermaid built-in themes: Default (uses your custom colors), Dark, Forest, and Neutral. The Default theme respects your custom color settings. The other themes apply their own palettes for a polished look without manual tuning.

Output Size:

Control how large the diagram appears in the issue panel after saving. Options range from Small (0.5x) to X-Large (2x), with Medium (1x) as the default.

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

Step 5 -- Save the Diagram to the Issue

Once you are satisfied with the preview, click Save. The diagram is stored on the Jira issue and displayed in the Mermaid+ Diagrams panel. Anyone who can view the issue will see the rendered diagram. Anyone with Edit Issues permission can click the edit button (pencil icon) in the panel to reopen the editor and modify the diagram.

All settings -- code, colors, font, theme, and output size -- are preserved when you re-edit. The diagram also adapts to Jira's dark or light mode automatically. When you save a diagram, the current Jira theme is recorded. If someone views the issue in a different theme later, text and background colors are adjusted for readability.

For full documentation on all features, see the Mermaid Plus Diagrams for Jira usage guide.

Which Diagram Types Work Best on Jira Issues?

Mermaid Plus Diagrams for Jira supports 26 diagram types. Not all of them are equally useful in the context of a Jira issue. Here are the diagram types that deliver the most value on Jira issues, along with guidance on when to use each one.

Flowcharts for Bug Reproduction Steps

Flowcharts are the single most useful diagram type on Jira bug tickets. A well-structured flowchart shows the exact path a user took through the application to trigger the bug, including decision points, error branches, and loops. This eliminates the back-and-forth between QA and developers about "how did you get there?"

Use flowcharts when:

• Documenting step-by-step reproduction paths for bugs
• Showing conditional logic in a feature request
• Illustrating approval workflows and escalation paths
• Mapping out process changes for improvement tickets

Key flowchart features to know:

• Directions: TD (top-down), BT (bottom-up), LR (left-right), RL (right-left)
• Node shapes: [Square], (Rounded), {Diamond}, ((Circle))
• Subgraphs: Group related steps together visually

Sequence Diagrams for API Flows

Sequence diagrams show how participants communicate over time, making them ideal for documenting API interactions directly on backend or integration tickets. When a developer picks up a ticket about an API endpoint, a sequence diagram on that ticket tells them exactly which services are involved and in what order messages flow.

Use sequence diagrams when:

• Documenting request/response flows between services
• Showing authentication and authorization sequences
• Illustrating event-driven architectures and message queues
• Describing retry logic, circuit breakers, and error handling flows

Class Diagrams for Design Discussions

Class diagrams model object-oriented relationships, which makes them valuable on design-phase tickets where the team needs to agree on data structures, inheritance hierarchies, and composition patterns before implementation begins.

Use class diagrams when:

• Discussing database schema changes on a feature ticket
• Reviewing data model proposals for new functionality
• Documenting existing class hierarchies for refactoring tickets
• Showing relationships between entities in a domain model

Other Useful Diagram Types on Jira Issues

Beyond the big three, these diagram types also have practical applications on Jira issues:

• State diagrams -- Show the lifecycle of an entity (order status, deployment states) on workflow-related tickets
• Gantt charts -- Display timelines and dependencies on epic-level tickets
• Mind maps -- Brainstorm feature scope or root causes on planning tickets
• ER diagrams -- Document database schema changes on data migration tickets
• C4 diagrams -- Illustrate system architecture on infrastructure or integration tickets

3 Copy-Paste Mermaid Examples for Jira Workflows

Below are three practical Mermaid examples designed for common Jira scenarios. Copy any of these into the Mermaid Plus Diagrams editor on a Jira issue and modify the labels to fit your situation.

Example 1 -- Bug Reproduction Flowchart

This flowchart documents the exact steps a user takes to trigger a checkout bug. Paste this on a Bug-type Jira issue to give developers an instant visual reproduction path.

graph TD
    A[User opens product page] --> B{Item in stock?}
    B -->|Yes| C[Add to cart]
    B -->|No| D[Show out of stock message]
    D --> E[User clicks notify me]
    C --> F[Proceed to checkout]
    F --> G{Logged in?}
    G -->|Yes| H[Enter shipping info]
    G -->|No| I[Redirect to login]
    I --> J[User logs in]
    J --> H
    H --> K[Select payment method]
    K --> L[Click Place Order]
    L --> M{Payment succeeds?}
    M -->|Yes| N[Order confirmed]
    M -->|No| O[Payment declined error]
    O --> P[User retries with different card]
    P --> K

Why this works on a Jira bug ticket: The developer reading this bug can immediately trace the path from "user opens product page" through the decision points to the failure at "payment declined error." No ambiguity, no missing steps, no guessing.

Example 2 -- API Integration Sequence Diagram

This sequence diagram shows the interaction between a mobile app, API gateway, backend service, and database during a user profile update. Paste this on a Story or Task ticket that involves API development.

sequenceDiagram
    autonumber
    actor User
    participant App as Mobile App
    participant GW as API Gateway
    participant Auth as Auth Service
    participant SVC as Profile Service
    participant DB as Database

    User->>App: Update profile form
    App->>GW: PUT /api/v1/users/42/profile
    GW->>Auth: Validate JWT token
    Auth-->>GW: Token valid, user_id=42
    GW->>SVC: Forward authenticated request

    SVC->>SVC: Validate input fields
    SVC->>DB: UPDATE users SET name=$1, email=$2 WHERE id=42
    DB-->>SVC: 1 row updated

    alt Profile update succeeds
        SVC-->>GW: 200 {user: {id: 42, name: "Updated"}}
        GW-->>App: 200 OK
        App-->>User: Show success toast
    else Validation fails
        SVC-->>GW: 400 {errors: ["Email format invalid"]}
        GW-->>App: 400 Bad Request
        App-->>User: Highlight invalid fields
    else Database timeout
        SVC-->>GW: 503 Service Unavailable
        GW-->>App: 503
        App-->>User: Show retry prompt
    end

Why this works on a Jira story ticket: When a developer picks up this story, they can see at a glance every service involved, the order of calls, and all three outcome branches (success, validation failure, database timeout). This is far more efficient than a paragraph describing "first the gateway validates the token, then forwards to the profile service, which updates the database, but if..."

Example 3 -- Class Diagram for a Design Discussion

This class diagram shows a proposed data model for a notification system. Paste this on a design-phase ticket to give the team a concrete visual to discuss and refine.

classDiagram
    class User {
        +int id
        +String email
        +String name
        +getPreferences() NotificationPreference
    }

    class NotificationPreference {
        +int userId
        +boolean emailEnabled
        +boolean pushEnabled
        +boolean slackEnabled
        +String slackWebhookUrl
    }

    class Notification {
        +int id
        +int userId
        +String type
        +String title
        +String body
        +DateTime createdAt
        +boolean read
        +markAsRead()
    }

    class NotificationTemplate {
        +int id
        +String name
        +String subjectTemplate
        +String bodyTemplate
        +render(context) String
    }

    class NotificationChannel {
        <<interface>>
        +send(notification, preference) boolean
    }

    class EmailChannel {
        +send(notification, preference) boolean
    }

    class PushChannel {
        +send(notification, preference) boolean
    }

    class SlackChannel {
        +send(notification, preference) boolean
    }

    User "1" --> "1" NotificationPreference : has
    User "1" --> "*" Notification : receives
    Notification "*" --> "1" NotificationTemplate : uses
    NotificationChannel <|.. EmailChannel
    NotificationChannel <|.. PushChannel
    NotificationChannel <|.. SlackChannel

Why this works on a Jira design ticket: The team can review the class relationships, method signatures, and the interface-based channel abstraction without reading through a lengthy design document. Comments on the ticket can reference specific classes: "Should NotificationTemplate.render() return HTML or plain text?" This keeps the design discussion focused and productive.

Mermaid Plus for Jira vs. Mermaid Plus for Confluence

If your team uses both Jira and Confluence, you might wonder how the Jira version compares to the Confluence version. Here is what is the same and what is different.

What Is the Same

• Mermaid syntax: Both apps use the same Mermaid.js syntax. Any diagram you create in one app will work in the other.
• 26 diagram types: Both apps support the full set of 26 diagram types including flowcharts, sequence diagrams, class diagrams, Gantt charts, mind maps, C4 diagrams, and more.
• Live preview: Both apps render your diagram in real time as you type.
• Color customization: Both apps offer five customizable colors (Node, Text, Border, Line, Background) with visual color pickers.
• Theme support: Both apps support Default, Dark, Forest, and Neutral themes.
• Font customization: Both apps let you choose font family and size.
• Syntax guide: Both apps include a built-in syntax reference accessible from the editor.
• Quick templates: Both apps provide one-click starter templates for all 26 diagram types.

What Is Different

Feature	Jira Version	Confluence Version
Location	Issue panel above Activity section	Macro embedded in page content
Diagram storage	Attached to the specific issue	Embedded in the Confluence page
Permissions	Edit Issues permission required to create/edit	Page edit permission required
Multiple diagrams	One diagram per issue panel	Multiple macros per page
Context	Issue-centric (bug, story, task)	Page-centric (documentation, knowledge base)
Viewing audience	Anyone who can view the issue	Anyone who can view the page
Dark mode	Auto-adapts to Jira theme	Follows Confluence theme

When to Use Each

Use Mermaid Plus for Jira when you need to attach visual context directly to a piece of work: a bug reproduction flow, an API design for a story, or a root-cause analysis on an incident. The diagram lives with the ticket and is part of the team's daily workflow.

Use Mermaid Plus for Confluence when you are writing long-form documentation, architecture decision records, onboarding guides, or runbooks. Confluence pages give you more space for narrative context alongside the diagram, and you can embed multiple diagrams on a single page.

Many teams use both: Confluence for the authoritative design document, and Jira for the quick visual reference on the implementation ticket that links back to the Confluence page.

Tips for Getting the Most Out of Diagrams on Jira Issues

Start with a Quick Template

The editor provides one-click starter templates for all 26 diagram types. Instead of writing Mermaid code from scratch, click a template, then modify the node labels and connections to match your scenario. This saves time and reduces syntax errors.

Use the Syntax Guide for Reference

Click the ? button in the editor header to open the full syntax reference. Browse all 26 diagram types with descriptions and code examples. Hover over any code block and click the insert button to load it into your editor. This is especially useful when you need a less common diagram type and cannot remember the exact syntax.

Keep Diagrams Focused

A Jira issue diagram should answer one specific question: "How does this bug reproduce?" or "What does this API flow look like?" Resist the temptation to put everything into a single diagram. If you need to show multiple aspects of a system, create focused diagrams on separate issues and link them together.

Choose the Right Output Size

Use the Output Size setting to control how large the diagram appears in the issue panel. For simple flowcharts with few nodes, Medium (1x) works well. For complex diagrams with many nodes and labels, consider Large (1.5x) or X-Large (2x) to ensure readability.

Match Your Jira Theme

If your team uses Jira in dark mode, select the Dark theme in the diagram settings. The diagram will render with high-contrast colors against a dark background. The Default theme uses your custom color settings and works best in light mode. The app also auto-adapts when viewers switch between dark and light mode.

Use the Confluence Version for Related Documentation

If a Jira issue needs extensive background documentation with multiple diagrams, create a Confluence page with the detailed explanation and embed multiple Mermaid diagrams there using Mermaid Plus for Confluence. Then add a single, focused summary diagram on the Jira issue and link to the Confluence page for the full picture.

Performance and Technical Details

Diagrams rendered with Mermaid Plus Diagrams for Jira are designed to be fast. The rendering process works as follows:

• On save: The Mermaid code is rendered to SVG and cached
• On issue load: The cached SVG is displayed instantly -- no JavaScript rendering required
• During editing: The Mermaid.js library is loaded only when the editor is open, not when viewing issues

This means diagrams on Jira issues add zero performance overhead to normal issue viewing. The Mermaid.js library is only loaded when someone opens the editor to create or modify a diagram.

Supported Diagram Types -- Complete List

Mermaid Plus Diagrams for Jira supports 26 diagram types. Here is the full list for reference:

Diagram Type	Keyword	Best Used For
Flowchart	graph / flowchart	Process flows, bug reproduction, decision trees
Sequence Diagram	sequenceDiagram	API flows, service interactions, message protocols
Class Diagram	classDiagram	Data models, OOP design, schema discussions
State Diagram	stateDiagram-v2	Entity lifecycles, workflow states, deployment states
ER Diagram	erDiagram	Database schemas, entity relationships
User Journey	journey	UX flows, satisfaction mapping
Gantt Chart	gantt	Project timelines, task dependencies
Pie Chart	pie	Proportional data, time allocation
Git Graph	gitGraph	Branch strategy, release workflows
Mindmap	mindmap	Brainstorming, feature scoping
Timeline	timeline	Milestones, release history
Requirement Diagram	requirementDiagram	Requirements traceability
C4 Diagram	C4Context	System architecture, service boundaries
Quadrant Chart	quadrantChart	Priority matrices, analysis charts
Sankey Diagram	sankey-beta	Flow volumes, resource allocation
XY Chart	xychart-beta	Bar and line charts, metrics
Block Diagram	block-beta	Component layouts, system blocks
Packet Diagram	packet-beta	Network packet structures
Kanban Board	kanban	Task board visualization
Architecture Diagram	architecture-beta	Infrastructure and service architecture
Radar Chart	radar-beta	Multi-axis comparisons
TreeView	treeView-beta	File/folder structures
Treemap	treemap	Hierarchical data visualization
Ishikawa	ishikawa	Root cause analysis, fishbone diagrams
Venn Diagram	venn-beta	Set relationships, team skill overlap
ZenUML	zenuml	Alternative sequence diagram syntax

Common Questions

Can multiple team members edit the same diagram?

Only one person can edit a diagram at a time. However, anyone with Edit Issues permission can edit the diagram after the previous editor has finished. Changes are saved atomically, so there is no risk of partial edits.

Do diagrams appear in Jira search results?

Diagrams are rendered as visual content on the issue. The Mermaid code is stored with the issue and contributes to the issue's content.

What happens if I delete a diagram?

You can clear the diagram by editing it and removing the code. The diagram panel remains on the issue but shows an empty state, ready for a new diagram.

Can I use Mermaid subgraphs?

Yes. Subgraphs are fully supported and are especially useful for grouping related steps in a flowchart. Wrap nodes in subgraph Name ... end to create visual groupings.

Does the app work with Jira Automation?

Diagrams are stored as part of the issue content. Jira Automation rules that reference issue fields will not directly interact with diagrams, but you can use automation rules to manage the issues that contain them.

Related Resources

• Mermaid Plus Diagrams for Jira -- full documentation -- detailed configuration, all settings, and complete syntax reference
• Create Mermaid diagrams in Confluence -- the Confluence version of this guide, covering macros, page embedding, and Confluence-specific features
• Mermaid troubleshooting FAQ -- solutions for common rendering issues, syntax errors, and display problems
• How to create sequence diagrams in Confluence -- deep dive into sequence diagram syntax with five copy-paste examples

Adding diagrams to Jira issues takes a process that used to require external tools, exported images, and constant re-attachment, and turns it into a few seconds of typing in an editor that lives right on the issue. Install Mermaid Plus Diagrams for Jira, paste one of the examples from this guide onto your next bug or story, and give your team the visual context they need to move faster.