Add a diagram to a Jira issue with Markdown

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

To add a diagram to a Jira issue with Markdown, open a Markdown document in the issue's Markdown panel, choose Insert and then From code, and edit the Mermaid starter it adds. Any fenced code block in one of 28 supported diagram languages, such as Mermaid, PlantUML, Graphviz or D2, renders as a picture in the panel.

#Before you start

  • You need to be allowed to add attachments to the issue.

  • Diagrams are drawn by Capable's hosted diagram service, so the diagram source is sent there to be rendered.

#Steps

  1. Open the issue's Markdown panel and click Add, or pick a document and click Edit.

  2. Put the cursor where the diagram should go.

  3. Choose Insert, then From code. A Mermaid graph TD starter is added.

  4. Edit the code. For another language, change the word after the opening three backticks, for example plantuml or graphviz.

  5. Check the picture in the preview, then click Save.

#If it does not work

  • The diagram shows as plain code. Check the language name after the backticks is one of the 28 supported, and that the code has no syntax errors.

  • It looks different from mermaid.js elsewhere. Diagrams are rendered on the server as images, so interactive features and some newer syntax may not carry over.

Diagrams as code, next to the work they describe.