If you write documentation in Markdown but need to post it to Jira, you’ve hit the wall: Jira has its own wiki markup language, and pasting Markdown directly doesn’t work — or doesn’t work reliably. The results depend on which version of Jira you’re using, which project type, and whether your admin has enabled anything.

This guide maps out every syntax difference, explains what actually works in each Jira context, and shows you how to do the conversion reliably.

Why Jira Doesn’t Just Support Markdown

Jira’s text formatting language (wiki markup) predates widespread Markdown adoption. It uses its own syntax that’s close to — but not the same as — Markdown. In Cloud and Server, Atlassian has gradually added Markdown-like support, but it’s incomplete and inconsistent across project types.

The result: the same pasted content renders differently in:

  • Jira Data Center/Server — pure wiki markup, very little native Markdown support
  • Jira Cloud (classic projects) — hybrid editor, some Markdown autocomplete on the Visual side
  • Jira Cloud (next-gen / team-managed projects) — rich text editor, accepts some Markdown on paste, no wiki markup at all

This distinction matters more than anything else in this guide.

Which Jira Version Are You Using?

Before converting anything, identify your environment:

Jira type How to tell Markdown support Wiki markup
Data Center / Server Self-hosted, URL isn’t atlassian.net None Full
Cloud — classic project atlassian.net domain, Text/Visual editor toggle Partial (autocomplete) Full
Cloud — next-gen project atlassian.net, no “Text” tab in editor Paste-in only None

For Data Center/Server and Cloud classic: Convert to wiki markup before pasting.
For Cloud next-gen: Paste Markdown directly into the rich text editor; basic formatting survives (bold, italic, lists), but tables and code blocks usually break.

The Complete Markdown → Jira Wiki Markup Conversion Table

Element Markdown Jira Wiki Markup
Heading 1 # Heading h1. Heading
Heading 2 ## Heading h2. Heading
Heading 3 ### Heading h3. Heading
Bold **text** *text*
Italic *text* _text_
Strikethrough ~~text~~ -text-
Inline code `code` {{code}}
Code block ```lang {code:lang}...{code}
Blockquote > text {quote}text{quote}
Link [text](url) [text\|url]
Image ![alt](url) !url!
Unordered list - item * item
Ordered list 1. item # item
Horizontal rule --- ----
Table header \| head \| \|\| head \|\|
Table cell \| cell \| \| cell \|

The differences look subtle but they trip people up constantly — especially *bold* becoming _italic_ in Jira (the opposite of how Markdown works).

Converting Code Blocks

This is where things get interesting. Jira uses macro syntax for code blocks:

Markdown:

```javascript
const greeting = 'Hello, world!';
console.log(greeting);
```

Jira wiki markup:

{code:javascript}
const greeting = 'Hello, world!';
console.log(greeting);
{code}

The language name goes as a parameter to the {code} macro. Supported languages include java, javascript, python, sql, xml, html, css, bash, ruby, php, and dozens more. If you omit the language, the block renders as plain preformatted text.

For inline code, Markdown uses backticks while Jira uses {{double curly braces}}:

Markdown Jira
`variable` {{variable}}
`npm install` {{npm install}}

Converting Tables

Tables are one of the clearest differences. Markdown uses a --- separator row to mark headers; Jira uses double pipes (||) for header cells and single pipes (|) for body cells.

Markdown:

| Name | Role | Access |
|------|------|--------|
| Alice | Admin | Full |
| Bob | Developer | Read/Write |

Jira wiki markup:

|| Name || Role || Access ||
| Alice | Admin | Full |
| Bob | Developer | Read/Write |

There’s no separator row in Jira. The header is inferred purely from whether the row uses || or |.

What Jira wiki markup tables don’t support:

  • Column alignment (:---: / ---: syntax is ignored)
  • Multi-line cells
  • Colspan or rowspan (requires the HTML macro)
  • Cell background colours (without the HTML macro)

If you need any of those, convert to HTML using our Markdown to HTML tool and paste using Jira’s HTML macro.

Converting Lists and Nesting

Both Markdown and Jira use * and # for lists, but Jira doesn’t use indentation for nesting — it uses repeated characters:

Markdown (nested):

- Item 1
  - Nested item
  - Another nested
- Item 2

Jira wiki markup (nested):

* Item 1
** Nested item
** Another nested
* Item 2

Each additional level of nesting repeats the character. Two levels deep is **, three is ***. Indentation in Markdown doesn’t translate automatically — you need to count nesting depth and repeat accordingly.

Mixed ordered/unordered nested lists work the same way:

* First level unordered
*# Second level ordered under unordered
*#* Third level unordered under ordered under unordered

Converting Blockquotes

Markdown blockquotes use > prefixes. Jira uses a {quote} macro:

Markdown:

> This is a quoted passage from the requirements document.
> It can span multiple lines.

Jira:

{quote}
This is a quoted passage from the requirements document.
It can span multiple lines.
{quote}

Nested blockquotes (> > text) aren’t directly supported in Jira wiki markup — you get one level.

Jira-Only Macros

Wiki markup has macros that have no Markdown equivalent. Knowing these is useful when you’re writing content that will only ever live in Jira:

Colour text:

{color:red}This text is red.{color}
{color:#0052CC}This text is Jira blue.{color}

Info/note/warning/tip panels:

{info}This is an informational note.{info}
{warning}Caution: this action cannot be undone.{warning}
{note}Note: configuration required.{note}
{tip}Pro tip: use keyboard shortcuts.{tip}

Panel with title and styling:

{panel:title=Important|borderColor=#ddd|titleBGColor=#f0f0f0}
Panel content here.
{panel}

No-format block (preformatted text, no syntax highlighting):

{noformat}
Plain text that should appear as-is.
Stack traces, log output, etc.
{noformat}

Jira issue link:

{jira:KEY-123}

These macros render as styled components in Jira but have no Markdown equivalent. If you’re round-tripping content (Jira → Markdown → Jira), you’ll lose these macros on the Markdown side.

What Doesn’t Convert Cleanly

Some Markdown features have no wiki markup equivalent:

Markdown feature In Jira
Footnotes [^1] Not supported
Definition lists Not supported
Task lists - [x] Use (/) and (x) emoji for checkmarks; not linked to issue checklists
Custom heading IDs {#anchor} Not supported
Strikethrough in tables Works, but renders inconsistently
HTML elements Use {html} macro (Cloud only, off by default)
Fenced code inside blockquotes Loses code formatting

For task lists specifically: Jira has a built-in checklist feature in Cloud, but it’s separate from the text editor and not accessible via wiki markup.

Using Our Markdown to Jira Converter

The fastest way to convert is with our Markdown to Jira tool. Paste your Markdown on the left, get Jira wiki markup on the right in real time.

The converter handles:

  • All heading levels (h1–h6)
  • Bold, italic, strikethrough
  • Inline code and fenced code blocks with language tags preserved
  • Tables with header row conversion (|| vs |)
  • Ordered and unordered lists with nesting depth
  • Blockquotes
  • Links and images
  • Horizontal rules

It’s particularly useful when you have long documentation pages to migrate, or you’re regularly posting Markdown from a blog or docs tool into Jira issues.

Which Editor Mode to Use

For Data Center/Server: always use wiki markup. It’s the native format. Click the Text tab in the issue editor, paste wiki markup, done.

For Cloud classic projects: the Text tab accepts wiki markup directly. The Visual tab is WYSIWYG. If you’re using the REST API to create or update issues, the description field accepts wiki markup for classic projects.

For Cloud next-gen (team-managed) projects: there’s no Text tab. The editor is rich text only. For basic formatting, paste Markdown and let it auto-convert. For tables and code blocks, paste HTML using your browser’s paste shortcut after converting with our Markdown to HTML tool.

For Jira Cloud API (creating issues programmatically): Cloud’s REST API v3 uses Atlassian Document Format (ADF), not wiki markup. You can’t paste wiki markup into the description field via the API on Cloud — you need to build an ADF document. Wiki markup is only supported in the Server/DC REST API. This is a significant pain point for teams automating Jira content creation.

Jira Wiki Markup Reference Cheat Sheet

Quick reference for the conversions you’ll use most often:

Text formatting:

*bold*           _italic_         -strikethrough-
+underline+      ^superscript^    ~subscript~
??citation??     {color:red}text{color}

Structure:

h1. Heading 1          h2. Heading 2          h3. Heading 3
----                   (horizontal rule)

Lists:

* Bullet             # Numbered
** Nested bullet     ## Nested numbered

Links and media:

[Link text|https://example.com]
[Page title|PAGE TITLE]     (Confluence-style, not standard Jira)
!image.png!                 !image.png|thumbnail!
^file.pdf                   (attachment link)

Macros:

{code:java}code here{code}

{quote}quoted text{quote}
{noformat}plain text{noformat}