Writing Markdown in Jira issues

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

Jira descriptions are fine for a paragraph or two. When an issue needs a spec, a README or a diagram, a Markdown document on the issue keeps it readable. These guides cover writing one.

Jira issue with an API style guide written in Markdown in the Markdown panel, with a table and a code block
A spec written in Markdown on a Jira issue, easier to read than a long description.

#Common tasks

You want to

Go to

Add a Markdown document to an issue

Use Markdown in a Jira issue, then Markdown editor modal

Start from a ready-made document

Start a Jira Markdown document from a template, then Templates

Draw a diagram as code

Add a diagram to a Jira issue with Markdown, then Diagrams in fenced code blocks

Add an image

Images in Markdown

#Guides in this section

Use Markdown in a Jira issueWrite a Markdown document on a Jira issue with a live preview, saved as a .md attachment everyone on the issue can read.Start a Jira Markdown document from a templateStart a Markdown document on a Jira issue from one of 17 built-in templates, such as a README, a spec or meeting notes.Add a diagram to a Jira issue with MarkdownDraw Mermaid, PlantUML, Graphviz and other diagrams in a Jira issue by writing them as code in a Markdown document.

Specs where the work is.