Guides / Markdown to Jira wiki markup

Markdown to Jira wiki markup: a translation guide

Jira's text formatting notation predates Markdown's dominance, and it shows: headings are h2. prefixes, monospace is double braces, links put the URL after the text with a pipe, and code blocks are {code} macros. If you draft tickets in Markdown (or paste from a README), here's exactly how everything translates.

Convert Markdown to Jira now →

Syntax mapping

Worked example

## Bug report

Clicking **Save** throws `NullPointerException`:

1. Open settings
2. Clear the name field
3. Click Save

See [the logs](https://logs.example.com) for details.

```java
user.getName().trim();
```

becomes:

h2. Bug report

Clicking *Save* throws {{NullPointerException}}:

# Open settings
# Clear the name field
# Click Save

See [the logs|https://logs.example.com] for details.

{code:java}
user.getName().trim();
{code}

The characters that trade places

Like Slack, Jira reuses Markdown's punctuation with different meanings — but with an extra twist on line starts. In Jira, a leading # is a numbered-list item, not a heading, and a leading * is a bullet, not emphasis. So a Markdown heading converted naively (# Title → left as-is) silently becomes list item number one. Similarly Jira's -strikethrough- uses a plain hyphen, which is why converters (including this one) only match it at word boundaries — otherwise every hyphenated-word would get struck through.

Where wiki markup still applies

Wiki markup is the native format of Jira Server and Data Center — descriptions, comments, and any multi-line text field. It also matters for automation: the Jira REST API v2 accepts wiki markup in description and comment bodies, and many integrations (Bitbucket smart commits, service-desk email handlers, scripted field updates) still speak it.

Jira Cloud is the caveat: its editor stores content as a JSON document format (ADF) and accepts Markdown-style shortcuts while typing. Pasting wiki markup into the Cloud editor won't render it. You'll still hit wiki markup in Cloud via the v2 REST API and older integrations — but if your target is the Cloud UI itself, you may not need to convert at all.

Gotchas worth knowing

• Nested lists multiply the marker: ** for a second-level bullet, ## for a second-level number, and *# mixes them. Markdown's indentation-based nesting has to be re-expressed this way.
• Curly braces are live syntax. Text containing {…} (Java generics annotations, JSON snippets) can trigger macros. Wrap such text in {{monospace}} or a {noformat} block.
• Code block languages are named differently. {code:javascript}, {code:java}, {code:sql} etc. — an unrecognized language falls back to plain text rather than failing.
• Line breaks are real. Unlike Markdown, a single newline in wiki markup produces a line break, and \\ forces one. Reflowed Markdown paragraphs keep their shape.

Tables in detail

Markdown's pipe tables and Jira's table notation are close cousins. This Markdown table:

| Env  | Status |
|------|--------|
| Prod | OK     |
| Test | Failed |

is written in Jira as:

||Env||Status||
|Prod|OK|
|Test|Failed|

Double pipes mark header cells, single pipes mark body cells, and there's no separator row — the header styling comes from the double-pipe syntax itself. Jira tables don't support column alignment, so Markdown's :---: colons have no equivalent and are dropped. An empty cell needs a space between pipes (| |) or Jira merges the columns.

FAQ

Does this work for Confluence too?

Largely yes — Confluence's legacy wiki markup shares this notation, and Confluence still offers an "Insert wiki markup" dialog that accepts it. Like Jira Cloud, modern Confluence stores pages in a different internal format, so wiki markup is an input method rather than the storage format.

Can I convert Jira markup back to Markdown?

Yes, Converticle converts both directions — useful for pulling a ticket description into a README or commit message. Jira-only concepts with no Markdown equivalent (underline, {color}, panels) don't survive the trip.

Why did my heading turn into "1." in Jira?

You pasted raw Markdown: Jira read the leading # as a numbered-list marker. Convert first — the heading needs to arrive as h1..

Try the Markdown to Jira converter →