Jira uses a proprietary text formatting notation that breaks when pasted into standard Markdown environments like GitHub Pull Requests, Obsidian, or static site generators. Developers migrating issues, building release notes, or copying ticket context are forced into tedious manual formatting.
This guide breaks down the syntax mapping and explains how to automate the conversion locally.
Atlassian Formatting vs. Standard Markdown
Atlassian’s older markup engine is fundamentally incompatible with GitHub Flavored Markdown (GFM) or CommonMark. Jira’s text formatting notation uses the same wiki markup family described in Atlassian’s wiki markup reference. Here is the exact translation map required to bridge the two formats:
| Feature | Jira Atlassian Markup | Standard Markdown |
|---|---|---|
| Headings | h1. Title | # Title |
| Bold Text | *text* | **text** |
| Italics | _text_ | *text* or _text_ |
| Code Blocks | {code:javascript} | Fenced code block with language |
| Inline Code | {{var}} | Inline code (single backticks) |
| Unordered List | * Item or - Item | - Item or * Item |
| Numbered List | # Item | 1. Item |
| Underline | +text+ | No Markdown equivalent (keep plain text) |
| Blockquotes | bq. Quote | > Quote |
For Hyperlinks, Jira uses [Link Title|https://url.com], which translates to [Link Title](https://url.com).
Jira Cloud’s newer editor stores content as Atlassian Document Format and accepts Jira Cloud Markdown shortcuts while typing, but copying legacy descriptions still requires text conversion. If you need to post Markdown notes back into Jira, you can use our Markdown to Jira Converter.
CLI Workflow: Converting with Perl
If you need to batch-convert exported Jira tickets locally, you can use built-in CLI tools like perl.
Here is a tested script that handles the most common transformations (headings, bold text, lists, code, and links).
Note: The script converts lists before headings and bold text. Otherwise, numbered lists starting with # and bullet points starting with * get mangled by the other rules.
# Example Jira input
printf 'h1. Sprint Goal\nh3. Scope\n*Authentication Service*\n* first item\n* second *bold* item\n# numbered step\nRun {{npm test}} first\n[View API Docs|https://api.internal.com]\n' > ticket.jira
# Convert the most common Jira wiki markup to Markdown
perl -pe 's/^# /1. /; s/^\* /- /; s/^h([1-6])\. /"#" x $1 . " "/e; s/\{\{(.+?)\}\}/`$1`/g; s/\*([^* ][^*]*)\*/**$1**/g; s/\[([^\]|]+)\|([^\]]+)\]/[$1]($2)/g' ticket.jira > ticket.md
cat ticket.mdOutput:
# Sprint Goal
### Scope
**Authentication Service**
- first item
- second **bold** item
1. numbered step
Run `npm test` first
[View API Docs](https://api.internal.com)For complex documents involving nested lists, {code} blocks and tables, CLI regex scripts become fragile, and those elements still need manual work or a proper parser.
Pre-Flight Checklist
Before committing your converted Markdown into your repository or public documentation, run this quick check:
- Verify Link Integrity: Check that
[title|url]links became[title](url). - Check Code Blocks: Ensure
{code}tags didn’t leak. They must be fully replaced by triple backticks. - Audit for Secrets: Double-check that translating the ticket didn’t inadvertently expose an internal IP or token that was hiding in Jira’s proprietary syntax.
- Inspect Table Headers: Jira’s table header syntax
|| Header 1 || Header 2 ||requires conversion to GFM header rows (| Header 1 | Header 2 |followed by|---|---|).
