Sharp Diagrams – Mermaid for Confluence and Jira: documentation
Sharp Diagrams draws Mermaid diagrams from text: in Confluence as a macro on the page, and in Jira in a panel that draws the Mermaid code blocks of the issue description. There are two apps with the same diagram engine: Sharp Diagrams – Mermaid for Confluence and Sharp Diagrams – Mermaid for Jira. Install the one for the product you use, or both.
Mermaid is a text format for diagrams. The Mermaid documentation lists every diagram type and its syntax: https://mermaid.js.org/intro/
Confluence: add a diagram
- Edit a page, type
/mermaidand choose Mermaid diagram. - The diagram editor opens. Write Mermaid code on the left, or pick a template from Start from.
- The preview on the right updates while you type. If the code has a mistake, the error and its line number appear under the code, and the last working diagram stays in the preview.
- Select Save, and publish the page.
To change a diagram later, edit the page, select the diagram and choose the edit (pencil) button.
Confluence: templates
The editor has templates for 11 diagram types: flowchart, sequence, class, state, entity relationship, Gantt, mind map, timeline, pie chart, user journey and Git graph. If you have already written your own code, the editor asks before a template replaces it.
Jira: diagrams from the issue description
- In the issue description, add a code block and set its language to
mermaid. Write the diagram code in the block. - Open the issue and choose Mermaid diagrams from the app actions button under the issue title. The panel stays on the issue after that.
- Every Mermaid code block in the description becomes its own diagram in the panel. Other code blocks are left alone.
The panel reads the description when the issue is opened. After you change the description, reload the issue to see the new diagram.
The diagram toolbar
Move the pointer over a diagram to show its toolbar. On touch screens the toolbar is always visible.
- − and + zoom out and in (50 % to 300 %), and Fit fits the diagram to the width again. A very wide diagram is shrunk only to 75 % so that its text stays readable, and the rest scrolls sideways.
- SVG and PNG download the diagram. The PNG is drawn at twice the size for sharp slides and documents.
- Copy code copies the Mermaid code
Light and dark mode
Diagrams follow the colour mode of Confluence and Jira: in dark mode they are drawn with Mermaid’s dark theme.
Export to PDF and Word
Confluence draws app content for PDF and Word exports on its servers, where the diagram can’t be drawn. The export therefore contains the diagram code as a code block, with a note that the drawing is on the page. To put a drawing in a document, download it as PNG or SVG from the toolbar.
Good to know
- Diagrams are drawn in the browser of the person viewing them, with Mermaid’s strict security level: links, click handlers and HTML inside diagrams are not run.
- Very large diagrams take a moment to draw the first time a page is opened, because the diagram engine loads only the parts a diagram needs.
- If your license isn’t active, the diagram isn’t drawn. The code is shown instead, so no content is lost.
Data and permissions
- Confluence: the diagram code is saved in the page. The app needs no permissions to Confluence data.
- Jira: the app reads issue content (
read:jira-work) with the permissions of the person viewing the issue, so the panel shows only what that person can already see. - The apps have no external connections and no storage of their own. Privacy policy: https://hdsoft.fi/en/products/atlassian/sharp-diagrams/privacy/
Support
Email support@hdsoft.fi. Support hours, response times and security reports: https://hdsoft.fi/en/products/atlassian/support/
