Jira Formatting: Markdown vs Wiki Markup
By the MDConverter team · Updated · 4 min read
Quick answer
Which syntax Jira understands depends on the editor. Jira Cloud’s current editor reads Markdown as you type: # for headings, **bold**, - bullets, triple backticks for code. Jira Data Center and Server, and any text field that uses Atlassian’s older wiki renderer, use wiki markup instead: h1. headings, *bold*, {code} blocks and ||table|| headers. Markdown pasted where wiki markup is expected shows up as raw symbols, and the reverse is also true. Markdown to Jira and Jira to Markdown convert between the two.
Which one does your Jira use?
- Jira Cloud (an address ending in
atlassian.net): when Atlassian introduced the new issue editor in 2019 it announced that wiki markup had been removed from it “in favor of full markdown support”. Descriptions and comments are written in the editor, which turns Markdown into formatting as you type. - Jira Data Center and Server (hosted by your company): text fields use wiki markup, with a Visual and a Text tab — the Text tab is where you type
h1.and{code}. - Integrations and imports: tools that write to Jira through the REST API version 2 use wiki markup for text fields, while version 3 takes Atlassian’s own document format. When Atlassian made the editor change it said wiki markup would stay available through version 2; check the version your tooling calls before relying on it.
If you are not sure, paste a short test: h2. Test on its own line. If it appears as “h2. Test”, your editor does not use wiki markup.
Jira Cloud: Markdown shortcuts
Atlassian lists these as converting while you type in a rich text field:
| Type | You get |
|---|---|
# to ###### and a space |
Heading levels 1–6 |
**bold** or __bold__ |
Bold |
*italic* or _italic_ |
Italic |
~~strike~~ |
|
\code`` |
Monospace |
[label](https://…) |
Link |
 |
Image from a URL |
* or - and a space |
Bulleted list |
1. or 2) and a space |
Numbered list |
[] and a space |
Action item (checkbox) |
> |
Quote |
--- or *** |
Horizontal rule |
| Three backticks | Code block |
:smile: |
Emoji |
Tables are not on that list: add one from the / quick-insert menu. Mentions use @. Atlassian says you can paste raw Markdown into the editor but not convert content back out to raw Markdown. It documents the typing shortcuts, not what happens when a whole block of Markdown is pasted, so test with a short snippet; if a paste arrives as plain text, type the shortcuts, or use Ctrl/Cmd + Shift + V to paste without formatting and re-apply it.
Jira wiki markup: the cheat sheet
Wiki markup is typed in the Text tab of Data Center and Server, and is what version 2 of the REST API uses. Each element next to its Markdown equivalent:
- Heading:
h1. Title…h6. Title(Markdown# Title) - Bold / italic:
*bold*,_italic_(Markdown**bold**,*italic*) - Strikethrough:
-deleted-(Markdown~~deleted~~) - Inline code:
{{code}}(Markdown backticks) - Code block:
{code:java}…{code}(Markdown triple backticks and a language) - Quote:
bq. one line, or{quote}…{quote}for several (Markdown>) - Bullets:
* item, nested** item(Markdown- item, indented) - Numbers:
# item, nested## item(Markdown1. item) - Link:
[text|https://example.com](Markdown[text](https://example.com)) - Image:
!image.png!— the file must be attached to the issue - Table:
||Header||Header||then|cell|cell|(Markdown pipes and a---row) - Rule:
---- - Panel:
{panel:title=Note}…{panel} - Colour:
{color:red}text{color} - Mention:
[~username]
Markdown
## Steps
1. Open **Settings**
2. Run `npm test`
| Env | Result |
| --- | --- |
| Staging | Pass |Result
Steps
- Open Settings
- Run
npm test
| Env | Result |
|---|---|
| Staging | Pass |
The same content written in Markdown, for Jira Cloud.
Markdown
h2. Steps
# Open *Settings*
# Run {{npm test}}
||Env||Result||
|Staging|Pass|The same content as wiki markup, for Data Center and Server. Paste it into the Text tab.
Converting between Markdown and Jira
- Markdown → wiki markup: Markdown to Jira turns headings, bold, links, code blocks with their language, tables and lists into wiki markup, ready to paste into the Text tab of Data Center or Server, or to send through the REST API version 2. Typical source: a GitHub pull request description or an AI-written bug report.
- Wiki markup → Markdown: Jira to Markdown converts the other way — code macros and their languages, panels, mixed lists, tables, images — for GitHub issues, READMEs and Git-based docs.
- Confluence: wiki pages in Confluence use a related but not identical syntax. See Markdown to Confluence and Confluence to Markdown.
- On Jira Cloud: a Markdown description already works: type it into the editor (or paste it and check the result). The converters are for the places that use wiki markup.
What each Jira understands
Where each syntax is read as formatting.
| App | Supported | Notes |
|---|---|---|
| Jira Cloud editor (issue view) | Yes | Markdown shortcuts as you type. Tables from the / menu. Wiki markup was removed from this editor in 2019. |
| Jira Data Center / Server | Yes | Wiki markup in the Text tab and fields. Visual tab for rich editing. |
| REST API version 2 | Partly | Wiki markup for text fields. Version 3 takes Atlassian Document Format instead. |
| Markdown in Data Center | No | Shows as plain text; convert it to wiki markup first. |
| Wiki markup in the Cloud editor | No | Shows as plain text such as “h2. Title”. |
Common mistakes and how to fix them
| Problem | Fix |
|---|---|
| A comment shows “h2. Title” or “{code}” as plain text | You are in an editor that uses Markdown (Jira Cloud). Write the heading as ## Title and the code block with triple backticks, or convert with Jira to Markdown. |
| A comment shows “## Title” and “bold” as plain text | The field uses wiki markup (Data Center or Server). Convert the text with Markdown to Jira and paste it in the Text tab. |
| In wiki markup, a # line becomes a numbered item instead of a heading | In wiki markup # starts a numbered list; headings are h1. to h6.. Markdown’s # heading is the opposite. |
| Bold looks right in a draft but appears as stray asterisks in Jira | Wiki markup uses single asterisks for bold (*bold*). Double asterisks are Markdown. |
| A table shows as one line of pipes | In wiki markup the header row needs double pipes (||Header||), and each row must be on its own line. In Jira Cloud, insert tables from the / menu instead of typing pipes. |
| An image shows as !image.png! text | The file is not attached to the issue. Attach it first; wiki markup images refer to attachments by name. |
Tools for this
- Markdown to Jira Convert Markdown to Atlassian Jira Ticket Syntax
- Jira to Markdown Convert Atlassian Jira Tickets to Clean GitHub Markdown
- Markdown to Confluence Put Markdown into Confluence Pages
- Markdown Formatter Tidy messy Markdown: consistent lists, headings, tables and spacing, with a linter for the rest.
Frequently Asked Questions
Frequently Asked Questions About Jira formatting
Comprehensive answers to common technical, formatting, security, and compatibility questions.
Jira Cloud’s editor does: Markdown typed into a description or comment is converted to formatting as you type. Jira Data Center and Server use wiki markup, so Markdown shows as plain text there until you convert it with Markdown to Jira.
In Jira Cloud, type three backticks. In wiki markup (Data Center, Server), wrap the code in
{code:language} and {code}, for example {code:java}. Both keep indentation, and wiki markup lets you name the language for syntax colouring.In Jira Cloud, use the / quick-insert menu and choose Table. In wiki markup, write the header row with double pipes (
||Name||Status||) and each row with single pipes (|API|Done|). Markdown to Jira converts a Markdown table for you.If the text is wiki markup, convert it with Jira to Markdown: code macros, panels, lists, tables and images become GitHub Flavored Markdown. In Jira Cloud the description is already Markdown-style, but copying it out gives rendered text, not source, so check headings and code after pasting.
They share most of the syntax —
h1., *bold*, ||tables|| — but Confluence’s code macro takes parameters such as {code:language=java} and its panels and macros differ. Use Markdown to Confluence for Confluence.Related reading
- Slack Formatting: What Works, and How Slack Differs from Markdown — Bold, code, quotes and links in Slack — the toolbar, typed markup, and the mrkdwn used by bots.
- How to Use Markdown in Notion: Import, Shortcuts and Export — Import Markdown into Notion, type with its shortcuts, and export pages back out.
- Markdown Code Blocks: Inline Code, Fences and Syntax Highlighting — Inline code, fenced blocks, language names for highlighting, diffs and nested backticks.