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.
If a coding agent writes your tickets, check its instruction file with the CLAUDE.md Reviewer so it knows which markup Jira expects.
Open Markdown to Jira converterWhen 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
- Draft the ticket in Markdown wherever you normally write.
- Convert it to Jira wiki markup — headings, bold, lists, tables, and code fences all change syntax.
- Paste the converted text into the Jira description field.
- Preview: bold text, h2. headings, and {code} blocks should render, with no stray asterisks.
- For API-created issues, send the converted wiki markup in the description field of the v2 REST API.
Example conversion
## Problem **Login** fails for SSO users. - Affects ~120 users - Started after `v2.14` deploy ``` ERR_SSO_STATE_MISMATCH ```
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.
Jira Markdown Table: Convert a Markdown Table to Jira
A Jira markdown table uses ||double pipes|| for headers and no separator row. Convert Markdown pipe tables into Jira wiki markup tables that render in 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.
How to Format Code Blocks in Jira
Wrap the code in a {code} macro, or use the code block button in the new editor. Markdown fences do not work in Jira. Covers language hints, {noformat}, and inline code.
Does Jira Support Markdown? What Works and What Does Not
Jira does not render pasted Markdown in description or comment fields. This guide shows which fields accept Markdown for Jira, which need wiki markup, and how to convert.
How to Paste Markdown Into Jira
Paste Markdown into Jira without broken formatting: convert to wiki markup first, then paste into the description or comment field. Covers tables, code blocks, and the API case.
Jira to Markdown: Convert Wiki Markup Back to Markdown
Convert Jira to Markdown: turn wiki markup from descriptions and comments — h2. headings, {code} blocks, ||header|| tables — into clean Markdown for docs, README files, and AI tools.
Reading for ticket work
Automate the Jira busywork, write epics that survive a sprint, and keep the sentences short.
Automate Everyday Tasks in Jira
A no-code guide for Jira admins and power users. It covers the rules that move, assign, and update issues, so you stop doing it by hand.
- No-code automation rules
- Written for admins and power users
- Everyday Jira processes, not certification prep
- Pairs with the Markdown to Jira tool
The Epic Guide to Agile
Covers the part most Scrum books skip: shipping on a schedule you can actually predict, and writing epics and stories that survive contact with a sprint.
- Epics, stories, and estimation
- Predictable release planning
- Practical Scrum, not certification prep
- Pairs with the Jira and epic tools
The Elements of Style (4th ed.)
The short book on plain sentences. Most of what makes a ticket or a spec readable is in the first forty pages.
- Strunk and White, fourth edition
- Rules of usage and composition
- Under 120 pages
- The shortest fix for bloated prose
Amazon affiliate links. We earn a commission on qualifying purchases at no extra cost to you.