Need AI Training/Help?CloudYeti.io/meet
MarkdownMe
Jira wiki markup guide

Jira Markdown vs Wiki Markup

Why Markdown breaks in Jira description fields, how Jira's own wiki markup differs, and a side-by-side of the syntax that trips people up.

Direct answer

Jira does not render standard Markdown in description and comment fields — it uses its own wiki markup: h2. instead of ##, *bold* instead of **bold**, {code} instead of triple backticks, and ||header|| tables instead of pipe tables. Jira Cloud's newer editor accepts some Markdown as you type, but pasted Markdown still arrives as plain text.

Open Markdown to Jira converter

When to use this

  • Your pasted ticket description shows literal ##, **, and ``` characters.
  • Tickets are drafted in Markdown (or by an AI assistant) and filed into Jira.
  • You automate ticket creation through the Jira REST API, which expects wiki markup in v2.

Steps

  1. Draft the ticket in Markdown wherever you normally write.
  2. Convert it to Jira wiki markup — headings, bold, lists, tables, and code fences all change syntax.
  3. Paste the converted text into the Jira description field.
  4. Preview: bold text, h2. headings, and {code} blocks should render, with no stray asterisks.
  5. For API-created issues, send the converted wiki markup in the description field of the v2 REST API.

Example conversion

Markdown input
## Problem

**Login** fails for SSO users.

- Affects ~120 users
- Started after `v2.14` deploy

```
ERR_SSO_STATE_MISMATCH
```
Jira wiki output
h2. Problem

*Login* fails for SSO users.

* Affects ~120 users
* Started after {{v2.14}} deploy

{noformat}
ERR_SSO_STATE_MISMATCH
{noformat}

Common mistakes

  • Do not paste **double-asterisk** bold into Jira — Jira bold is a single asterisk, so the extra ones render literally.
  • Do not use # for headings; in Jira wiki markup # starts a numbered list item.
  • Do not assume Cloud and Data Center behave the same — the old editor and API fields are strict wiki markup.

FAQ

Does Jira support Markdown at all?
Jira Cloud's newer editor converts some Markdown as you type (like # heading or **bold**), but pasting a full Markdown document does not render it, and Jira Data Center/Server plus the v2 REST API use wiki markup only.
What are the biggest syntax differences?
Headings: ## becomes h2. — Bold: **text** becomes *text* — Italic: *text* becomes _text_ — Code fence: ``` becomes {code} — Inline code: `x` becomes {{x}} — Tables: |---| separator rows disappear and headers use ||.
Why does # break my numbered lists and headings?
In Jira wiki markup, # at line start means an ordered-list item, not a heading. A pasted Markdown heading like '# Overview' renders as '1. Overview'. Use h1. through h6. for headings.
Which format does the Jira REST API expect?
The v2 API renders wiki markup in description and comment bodies. The v3 API uses Atlassian Document Format (ADF) JSON instead — converted wiki markup is for v2, ADF for v3.

Related Jira guides

Markdown Acceptance Criteria to Jira

Convert Markdown acceptance criteria into Jira wiki markup that stays readable in issue descriptions.

AI Coding Notes to Jira Ticket

Turn rough AI coding session notes into a Jira implementation ticket with scope, telemetry, and tests.

QA Repro Steps Jira Template

Format QA repro steps, environment details, evidence, and acceptance criteria as a Jira bug ticket.

Markdown Table to Jira

Convert Markdown pipe tables into Jira wiki markup tables — double-pipe headers, no separator row — so they render inside descriptions and comments.

Markdown Code Blocks to Jira

Turn Markdown fenced code blocks into Jira {code} macros with language highlighting, and use {noformat} for logs and stack traces.