Mermaid diagrams on a Jira work item.

On this page: What it does · Add a diagram · Edit and versions · Two people at once · Order, delete and undo · Viewing a diagram · Cloning a work item · Permissions · Show the panel on every work item · Size limits · Limits · Troubleshooting · Privacy and security · Contact

What it does

Mermaid Live Preview for Jira adds a Mermaid diagrams panel to Jira Cloud work items. You type Mermaid code, see the diagram as you type, and save it on the work item.

A work item can hold several diagrams, each with an optional title, in the order you choose. Diagrams are drawn with Mermaid 12, and the editor colours the code as you type.

There is no Mermaid account to create or link. The app has no backend of its own and only talks to your Jira.

Add a diagram

1. A Jira admin installs Mermaid Live Preview for Jira from the Atlassian Marketplace.
2. Open a work item. Click Apps and choose Mermaid diagrams. The panel appears above Activity and the editor opens.
3. Pick one of the 12 examples or type your own code. If you paste a ```mermaid block, the fences are removed for you.
4. Give the diagram a title if you like.
5. Click Add diagram.

The examples are flowchart, sequence, class, state, Gantt, pie, mindmap, timeline, journey, ER, architecture and kanban.

The Apps button is only shown to people who may edit the work item. Once the panel is on a work item, it stays there.

Edit and versions

Click Edit on a diagram. The editor opens with the latest saved version. If someone changed it since your page loaded, the editor says so.

Versions in the editor lists up to 20 saved versions of that diagram. Pick one to load it, then save. A large diagram keeps fewer versions. See Size limits.

When the code has a mistake, the preview shows the line, a marker under the spot, and what Mermaid expected.

Two people at once

When you save, the app checks whether someone else saved the same diagram, its code or its title, after you opened the editor. If so, you choose:

• Load their version. The editor shows what they saved.
• Save mine anyway. Their version is put in Versions first. If it can't be kept there, your save is refused and nothing is replaced.

If someone saves right after you, the editor stays open with your text and says so. Two people working on different diagrams of the same work item never get in each other's way.

Jira has no way to lock a value. Two saves that land at the same moment can still cross. The app then tells the person whose save was replaced, when it can.

Order, delete and undo

• Move up and Move down (the arrows) change the order of the diagrams on the work item.
• Delete asks first, then removes the diagram and its versions. If someone else changed the diagram since your page loaded, it is not deleted. The panel shows the latest version instead.
• Undo appears right after you delete and brings the diagram and its versions back. It stays until you reload the page or make another change.

Viewing a diagram

• Fit, zoom and Open large. Diagrams fit the width of the panel. Hover over a diagram, or tab to it, to zoom or to open it large.
• Keys on a focused diagram. + and - zoom, 0 fits, the arrow keys move, and Enter opens it large.
• Links inside a diagram open in a new tab.
• Light and dark. The panel follows Jira's theme.

Cloning a work item

Jira's Clone does not copy the diagrams. A clone starts without them and without the panel.

To take the diagrams along, open the clone, click Apps and choose Mermaid diagrams. The panel offers to copy the diagrams from the original. Nothing is copied until you click it, and the original is not changed. Versions are not copied: the clone starts its own.

Permissions

The app uses Jira's own permissions:

You can	When Jira lets you
See the diagrams of a work item	See the work item (Browse projects)
Add, edit, reorder or delete diagrams	Edit the work item (Edit issues)

The app works as you, so it can only do what you can do. Jira checks every change itself and refuses a change you have no permission for.

Show the panel on every work item (Jira admins)

By default, someone adds the panel to a work item with Apps. A Jira admin can show it on every work item: open the panel's ••• menu and choose Show for all work items.

Careful: Hide from all work items also removes the panels that people added themselves.

Size limits

• 32 KB per diagram. Jira allows 32 KB per issue property, and each diagram has its own. A typical diagram is well under 1 KB. The editor shows how much is used and won't save past the limit.
• Versions. The versions of a diagram have their own 32 KB. When that is full, the oldest versions go first. For a diagram over about 16 KB, Versions holds one or two. A version that Save mine anyway just replaced is never the one that goes.

Limits and what is not confirmed yet

• Jira Cloud only. Not Jira Data Center or Server.
• In its own panel. Diagrams show in the Mermaid diagrams panel above Activity, not in the description.
• Not in the Jira Service Management portal. Portal customers and anonymous visitors of public projects don't get the panel.
• Clones. Jira's Clone does not copy diagrams. See Cloning a work item.

Not yet confirmed. We have not tested these on a real Jira site yet, so we don't promise them:

• Read-only users: that someone who can see but not edit the work item sees the diagrams without Add, Edit, Move and Delete.
• Moving a work item to another project: whether the diagrams stay.
• Uninstalling: whether the diagrams stay on the work items. See Privacy and security.
• SVG and PNG download from the panel inside Jira.
• Narrow views: the panel in a board's side view and in the work item view that opens from a board.
• Browsers: Firefox and Safari.

If you rely on one of these, try it on a test work item first, and tell us what you see.

Troubleshooting

You see	What it means
No Apps button, or no Mermaid diagrams under it	The button is only shown to people who may edit the work item. Check that you have edit permission and that the app is installed. A Jira admin can also show the panel on every work item.
The editor says someone else saved the diagram	Someone saved it after you opened the editor. Choose Load their version or Save mine anyway. See Two people at once.
The editor won't save because the diagram is too large	A diagram can be up to 32 KB. See Size limits.
Delete did nothing and the panel shows another version	Someone else changed the diagram since your page loaded. Check the latest version, then delete again if you still want to.
A card says a diagram can't be read here	The stored value was written by a newer version of the app, or changed by hand or by another tool. The app shows it without Edit or Delete, and never overwrites or deletes it.
A clone has no diagrams	Jira's Clone does not copy them. See Cloning a work item.

Privacy and security

Where is data stored? On the Jira work item itself, as Jira issue properties. Issue properties are Jira's built-in way to store small values on a work item. Nothing is stored anywhere else. The app has no app storage and no database.

Issue property	What is in it
dortus-mermaid-d-<id>, one per diagram	The diagram's id, title and Mermaid code, and when it was created and last saved
dortus-mermaid-h-<id>, one per diagram	Its earlier versions: the code and when each was saved. Up to 20
dortus-mermaid-order	The order of the diagrams on the panel

Jira itself also keeps a small property on the work item to remember that the panel was added.

Is personal data stored? The app stores no account IDs, names or email addresses. It only stores what is in the table above. Personal data ends up there only if you type it into a diagram or a title yourself.

Who can read the diagrams? Everyone who can see the work item, in the panel or through Jira's REST API. Issue properties are not private to the app. Other apps on your site that may read Jira work items can read them too.

What permissions does the app ask for? Two Jira scopes: read:jira-work and write:jira-work. The app uses them to read and save its own issue properties, and to ask Jira whether you may edit the work item. It also lets Mermaid use inline styles in its own frame, which Mermaid needs to draw.

Where does the app run? In the browser of the person viewing the work item. It talks only to your Jira, as that person. It makes no other network calls and loads no fonts, images or scripts from elsewhere. There is no app backend.

What does the app send outside Atlassian? Nothing. There is no Dortus server behind the app, and nothing is sent to Dortus or to any third party. There is no analytics and no tracking.

How are diagrams deleted? With Delete in the panel. It removes the diagram's versions first, then the diagram. If the versions can't be removed, the diagram stays. Deleting the work item deletes its diagrams with it.

What happens if I uninstall? Not yet confirmed. Issue properties are Jira data, not app storage, so we expect the diagrams to stay on the work items. To remove them, delete them in the panel before you uninstall.

The app is built on Atlassian Forge, for Atlassian's Runs on Atlassian programme. Full policy: Privacy policy, section 3.7. Terms: Terms of service.

Contact

Questions, a bug, or an idea? Email support@dortus.com. The person who builds the app reads every message. Please include your site URL, the work item key, your browser, what you expected and what happened.