Markdown to Jira: A Field Guide to Wiki Markup

The first time I pasted a tidy GitHub pull-request body into a Jira description field, it came out as a wall of hashes and asterisks. My ## Summary heading was the literal text "## Summary." My **blocker** was the word blocker with a stray pair of asterisks on each side. The fenced code block kept its three backticks and rendered as a single gray line. Jira had silently rejected every Markdown convention I use everywhere else, because Jira does not speak Markdown. It speaks its own wiki markup, and the two look similar enough to fool you and different enough to break.

If you live in GitHub, VS Code, and Slack all day, that mismatch is a daily papercut. This guide walks through exactly where Markdown and Jira wiki markup diverge, shows a worked conversion, and points you at a converter that does the swap in one paste.

Why Jira refuses your Markdown

Jira's wiki markup predates Markdown becoming the default everywhere. When Atlassian built the description and comment editors, the token for a heading was already h1. and the token for bold was already a single asterisk. Markdown showed up later and never replaced it. Some newer cloud instances added a Markdown-ish autoformat mode, but it is inconsistent between projects and falls apart on code blocks and tables, which are exactly the parts you most want to keep intact.

So the safe move is to convert first and paste markup Jira already understands. The conversion is mechanical once you know the mapping, but there are a handful of traps that bite everyone at least once.

The headings trap: Jira uses h1.

In Markdown you count hashes. One hash is a top-level heading, two is a section, and so on down to six. Jira throws the hashes out entirely and uses a token instead: the letter h, the level number, a dot, and a space.

• Markdown # Title becomes Jira h1. Title
• Markdown ## Section becomes Jira h2. Section
• Markdown ### Subsection becomes Jira h3. Subsection

The dot matters and so does the space after it. h2.Section with no space will not render as a heading in most instances. If you copy a heading by hand and forget the space, the line just sits there as plain text, which is a maddening bug to chase because nothing errors out, it simply does not format.

One nice detail: some writers pad headings with trailing hashes for symmetry, like ## Done ##. Markdown strips those silently. A good converter does too, so you still get a clean h2. Done rather than h2. Done ##.

The bold trap: a single asterisk

This is the rule that catches the most people, including me, the second time around. In Markdown, bold is two asterisks: **shipped**. In Jira wiki markup, bold is one asterisk: *shipped*. A single asterisk in Markdown means italic, so the two systems use the same character for opposite jobs.

If you paste raw Markdown bold into Jira, **shipped** renders as the word shipped wrapped in one literal asterisk on each side, because Jira reads the inner pair as bold and leaves the outer pair as text. It looks broken in a subtle, easy-to-miss way.

Italic flips too. Jira uses underscores, not asterisks. Markdown *note* or _note_ both become Jira _note_. And because bold and italic share the asterisk, order of operations matters: you have to handle the double-asterisk bold before the single-asterisk italic, or you mangle the text. A converter that gets the order wrong will turn **bold** into a half-italicized mess. Strikethrough also changes, from ~~old~~ to -old- with single hyphens.

A worked example

Here is a small chunk of Markdown, the kind that lands in a Jira ticket every day:

## Sprint goals

We **shipped** the export job. Run `npm run build` before deploy.

| Owner | Status |
| --- | --- |
| Ada | done |

Run it through the converter and Jira wiki markup comes back:

h2. Sprint goals

We *shipped* the export job. Run {{npm run build}} before deploy.

||Owner||Status||
|Ada|done|

Walk through what changed. The ## became h2. with its space. The double-asterisk bold collapsed to a single asterisk. Inline code in backticks became {{monospace}} with double braces. The table header row picked up double pipes (||Owner||Status||), the dashed separator row vanished entirely because Jira has no such line, and the body row kept single pipes. Paste that block into a description field and it renders as a real heading, real bold, real monospace, and a real table with a bold header.

Fenced code blocks follow the same logic outside this example: ``` `js `` opens a {code:js} panel and closes with {code}, while a language-less fence becomes a plain {code} panel. Links flip from text to [text|url], and blockquotes go from > to bq.`.

Do the swap in one paste

You can memorize all of this, and after enough tickets you will. But the practical answer is to let a tool do the eight or nine substitutions at once so you never ship a stray asterisk. Paste your Markdown into the Markdown to Jira converter, and the wiki markup updates live as you type — headings to h1., bold to single asterisks, fences to {code} panels, tables to ||header|| rows — with a copy button that hands you something ready to drop into a ticket. Everything runs in your browser tab, so an internal incident write-up or an unreleased spec never leaves your machine.

The reverse trip is sometimes useful too. If a teammate hands you Jira-flavored text and you want it back in a portable format, or you are pulling content out of a ticket to put in a repo, the HTML to Markdown converter is a handy companion for getting rendered content back into clean Markdown you can edit anywhere.

The takeaway

Markdown and Jira wiki markup rhyme but do not match. Headings drop their hashes for h1. Bold drops one asterisk. Italic switches to underscores. Tables grow double pipes and lose their separator row. None of it is hard, all of it is fiddly, and a single missed space or extra asterisk renders as broken text with no warning. Convert once, paste clean, and stop retyping tickets by hand.

---

Made by Toolora · Updated 2026-06-13