# Use Markdown in a Jira issue

To use Markdown in a Jira issue, open the issue's **Markdown** panel and click **Add**. Give the document a **Title**, write Markdown in the editor while the preview updates beside it, and click **Save**. The document is stored as a .md attachment on the issue and appears as its own tab in the panel.

---

## Before you start

* Capable Markdown for Jira must be installed on your Jira site.
* You need to be logged in and allowed to add attachments to the issue.

---

## Steps

1. Open the issue. If the Markdown panel is not showing, click **Markdown** among the app buttons under the issue summary.
2. In the panel, click **Add**, or **Add Markdown** if the issue has no documents yet. The **Add Markdown** editor opens.
3. Type a **Title**. It becomes the name of the .md file.
4. Write your Markdown. The preview beside it shows how it will look.
5. Use the toolbar for formatting, and **Insert** to add a diagram or an image.
6. Click **Save**.

---

## What happens next

The document shows as a tab in the Markdown panel with a rendered preview, and as a .md file in the issue's attachments. Anyone who can see the issue can read it. Add as many documents as you like; extra tabs collapse into a **More** menu.

![Jira issue Payments service runbook with a Markdown panel showing a Payments runbook tab, rendered with a health checks table and numbered steps, and Edit and Add buttons](https://help.gocapable.com/images/f4c7476c-d3d2-4c7d-8746-af7731496526.webp)

A saved document shows as a tab in the Markdown panel, rendered with its tables and lists.

📝

Images must be referenced by web address. The editor has no image upload, and relative paths from a repository do not resolve in Jira.

---

## Related

### [Markdown (issue panel)](https://help.gocapable.com/jira-markdown/markdown-issue-panel.html)

The issue panel in full.

### [Markdown editor modal](https://help.gocapable.com/jira-markdown/markdown-editor-modal.html)

Every control in the editor.

### [Start a Jira Markdown document from a template](https://help.gocapable.com/jira-markdown/start-a-jira-markdown-document-from-a-template.html)

Start from a ready-made document.

### [Writing Markdown in Jira issues](https://help.gocapable.com/jira-markdown/writing-markdown-in-jira-issues.html)

More guides for writing Markdown in Jira.

---

_Proper documents, right on the issue._