# Writing Markdown in Jira issues

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](https://help.gocapable.com/images/49d48ebc-b257-491e-8820-499f26e71dfe.webp)

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](https://help.gocapable.com/jira-markdown/use-markdown-in-a-jira-issue.html), then [Markdown editor modal](https://help.gocapable.com/jira-markdown/markdown-editor-modal.html)                                                 |
| Start from a ready-made document    | [Start a Jira Markdown document from a template](https://help.gocapable.com/jira-markdown/start-a-jira-markdown-document-from-a-template.html), then [Templates](https://help.gocapable.com/jira-markdown/templates.html)                                     |
| Draw a diagram as code              | [Add a diagram to a Jira issue with Markdown](https://help.gocapable.com/jira-markdown/add-a-diagram-to-a-jira-issue-with-markdown.html), then [Diagrams in fenced code blocks](https://help.gocapable.com/jira-markdown/diagrams-in-fenced-code-blocks.html) |
| Add an image                        | [Images in Markdown](https://help.gocapable.com/jira-markdown/images-in-markdown.html)                                                                                                                                                                                                                                      |

---

## 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.](https://help.gocapable.com/jira-markdown/use-markdown-in-a-jira-issue.html)[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.](https://help.gocapable.com/jira-markdown/start-a-jira-markdown-document-from-a-template.html)[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.](https://help.gocapable.com/jira-markdown/add-a-diagram-to-a-jira-issue-with-markdown.html)

---

## Related

### [How it works](https://help.gocapable.com/jira-markdown/how-it-works.html)

The behaviour worth understanding.

### [Managing Markdown documents in Jira](https://help.gocapable.com/jira-markdown/managing-markdown-documents-in-jira.html)

Edit, delete and find documents.

### [Frequently asked questions about Markdown in Jira](https://help.gocapable.com/jira-markdown/frequently-asked-questions-about-markdown-in-jira.html)

Quick answers to common questions.

---

_Specs where the work is._