Mermaid Diagrams for Jira
Setup & Usage Guide
Installation
Install Mermaid Diagrams for Jira from the Atlassian Marketplace. It auto-renders mermaid code blocks in issue descriptions and comments.
No configuration is required. The app works immediately after installation.
Working in Confluence instead? See Mermaid Macros for Confluence, the companion app that adds a Mermaid Diagram macro to the page editor.
How It Works
The Jira app automatically scans your issue descriptions and comments for Mermaid code blocks. When it finds one, it renders the diagram inline in a dedicated panel.
To add a diagram, paste your Mermaid code into a code block in the Jira editor. You don't need to set a code-block language — Atlassian's editor doesn't list mermaid as an option, and the app recognizes Mermaid automatically from the diagram type on the first line:
```mermaid
flowchart LR
A[Start] --> B[Process]
B --> C{Decision}
C -->|Yes| D[Done]
C -->|No| B
```
Supported Diagram Types
Features
Zoom & Pan
Zoom in and out and move around complex diagrams using your mouse, trackpad, or keyboard.
Export & Copy
Download or one-click copy any diagram as SVG or PNG.
Dark & Light Mode
Theme-aware rendering automatically syncs with your Jira theme, re-rendering diagrams with the correct color palette when you switch modes.
Full-Screen & Pop-Out
Open any diagram in a larger pop-out or full-screen view for a distraction-free look at complex diagrams.
View Source
Toggle between the rendered diagram and the raw Mermaid source code to inspect or copy the syntax.
Per-Diagram Error Handling
If a diagram has a syntax error, the app surfaces a clear, per-diagram message instead of breaking the panel.
Where Diagrams Appear
- Sidebar panel: A compact preview in the right sidebar of any Jira issue. Click "Expand" for the full view.
- Full-width panel: Below the issue description, with full zoom, pan, and export controls.
Diagrams are detected in both issue descriptions and comments, including paginated comments.
Learning Mermaid syntax
Mermaid is an open text-to-diagram syntax — the same code works here, in any other Mermaid tool, and in plain text files. Three places worth knowing:
- Our Mermaid cheat sheet — copy-pasteable starters for the diagram types teams actually use in Jira and Confluence, plus the six tips that save the most time.
- mermaid.js.org — the official documentation, and the complete reference for every diagram type and option.
- Mermaid Live Editor — a scratchpad for drafting and checking syntax before you paste it in.
FAQ
My diagram isn't rendering. What should I check?
Make sure the first line of the code block is a valid Mermaid diagram type (e.g. flowchart TD, graph LR, sequenceDiagram). You do not need to set the code block's language to "mermaid" — Atlassian's editor doesn't offer that option, and the app detects Mermaid automatically from the content. If it still doesn't appear, validate your syntax in the Mermaid Live Editor.
Does the app modify my Jira data?
No. The app has read-only access and never creates, modifies, or deletes any content.
Does it work with Confluence?
Yes — Confluence support is a separate app called Mermaid Macros for Confluence. It adds a Mermaid Diagram macro you insert via /Mermaid in the page editor. See the Mermaid Macros for Confluence guide for setup and usage.
Can I draft diagrams with AI?
Yes — if your site has Rovo (included in Atlassian Standard and higher plans), ask it for a diagram in plain English: "make me a flowchart of our deployment process, in Mermaid syntax." Paste the code block it returns into an issue description or comment, and the panel renders it as a live diagram.
The dates on my Gantt chart run into each other. Can I fix it?
Mermaid labels a Gantt axis with full dates (2026-05-01) and doesn't thin the ticks out when they won't fit, so a chart with many ticks in a narrow column can overlap. Add axisFormat %b %d and tickInterval 1week to your source for clean weekly ticks like Jul 05. Expanding the diagram to full screen also gives the axis more room. The Mermaid cheat sheet has a worked example.
Is my data sent to external servers?
No. Rendering happens entirely in your browser, and the app itself never calls any service outside Atlassian — no analytics, no tracking, nothing phones home. Your diagram source stays in Jira unless you deliberately take it somewhere: exporting an image, for example, writes a file to your own device. See our Security Statement for details.
Support
Need help? Reach out to us: