Mermaid Diagrams for Jira

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:

Supported Diagram Types

The app renders 20+ diagram types, everything the bundled Mermaid release supports:

Features

Everything in this section is part of the core app; none of it requires Pro.

Pro: Optional Styling Upgrade

Version 4 adds Pro, an optional upgrade that is entirely about styling: no core feature has been moved behind it.

• •Nine designed styles: Boardroom, Sketchbook, Blackboard, Cupertino, Workshop, Phosphor, Blueprint, Newsprint, and Aurora. Each is switchable per diagram, comes with a matching bundled font, and covers every diagram type.
• •Right-angle connectors: one toggle for orthogonal (ELK) edge routing that keeps large flowcharts, state and class diagrams readable. Boardroom turns it on automatically.
• •Copy style as code: stamp a style into the diagram source itself, so it renders identically for every viewer, with no configuration.

Version 3 remains free forever; sites that stay on v3 keep everything they have. Updating to v4 starts a subscription: $0 for teams of 10 or under. Current pricing is on the app's Atlassian Marketplace pricing tab.

Where Diagrams Appear

• •Sidebar section: A collapsible "Mermaid Diagrams" section in the right-hand column of the issue, with a diagram count badge and compact previews. It appears automatically on any issue that contains Mermaid code. It's a small strip, so look for it among the issue's other context fields. Click "Expand" for the full view.
• •Full-width panel: Below the issue description, with full zoom, pan, and export controls. If it isn't showing, open it from the issue's … (more actions) menu.

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.

Creating diagrams via the REST API

There is no app-specific API to learn: the app detects Mermaid in ordinary code blocks, so anything that can write an issue description or comment through Jira's standard REST API can create or edit diagrams. Scripts, automation rules, and AI assistants included.

Write the issue body as ADF (Jira's /rest/api/3/issue and comment endpoints accept it) and include a codeBlock node with language: "mermaid":

{
  "type": "codeBlock",
  "attrs": { "language": "mermaid" },
  "content": [
    { "type": "text", "text": "flowchart TD\n" },
    { "type": "text", "text": "    A[Start] --> B{Works?}\n" },
    { "type": "text", "text": "    B -->|Yes| C[Ship]\n" },
    { "type": "text", "text": "    B -->|No| D[Debug]" }
  ]
}

Adjacent text nodes concatenate, so one node per diagram line keeps payloads readable; a single text node with \n escapes works identically.

• •Descriptions and comments both work: the panel scans them all and labels where each diagram came from.
• •Editing is just editing the text: update the description or comment through the same API and the diagram re-renders from the new source.
• •Untagged code blocks are detected too (Jira's language dropdown has no "mermaid" entry, so human-created blocks usually aren't tagged); the app recognizes Mermaid by its first line. For automation, setting language: "mermaid" is still the explicit, reliable path.

FAQ

Support

Need help? Reach out to us: