How to convert Jira to Markdown
Jira text is stored as wiki markup: h2. Title for a heading, *text* for bold, {code} around code and ||Name|| for a table header. Markdown tools do not read that syntax. A jira to markdown converter reads the markup, builds a tree of headings, lists, tables and code, and writes the same tree as Markdown.
That makes it useful when you move tickets into GitHub issues, a README or a wiki, paste a description into a pull request or a chatbot prompt, or leave Jira Server. The conversion runs in your browser, and the text is not uploaded. The Privacy Policy has the details.
What each part becomes
- Headings:
h1.toh6.become one to six hash marks. - Text styles:
*bold*becomes**bold**,_italic_becomes*italic*,-strike-becomes~~strike~~and{{mono}}becomes a code span. - Links and images: a link with a pipe between text and address becomes a Markdown link, and an image between exclamation marks becomes an image with its alt text.
- Lists: stars and hashes can be mixed and nested. A hash is a numbered item and a star is a bullet, at any depth.
- Code:
{code:java}becomes a fenced block with the language, and{noformat}becomes a fence with none. - Quotes and rules:
{quote}andbq.become block quotes, and----becomes a rule.
A worked example
This Jira text has a heading, a nested list, a table and a Java block:
h3. Steps
# Open the reset link
# Choose a password
#* at least 12 characters
||Browser||Fails||
|Chrome|(x)|
{code:java}
int ttl = 3600;
{code}The converter writes this Markdown. The (x) emoticon becomes an emoji and the table gets the divider row that Markdown requires:
### Steps
1. Open the reset link
2. Choose a password
- at least 12 characters
| Browser | Fails |
| --- | --- |
| Chrome | ❌ |
```java
int ttl = 3600;
```Panels, info boxes and quotes
Jira has colored boxes: info, tip, note, warning and the general panel. Markdown has only the block quote, plus the alert syntax that GitHub shows as a colored box. With GitHub alerts, info becomes NOTE, tip becomes TIP, note becomes WARNING and warning becomes CAUTION. A panel title becomes a bold line inside the box.
Choose plain block quotes when the Markdown goes anywhere other than GitHub. Each box is then a quote that starts with a bold label such as Warning, so the meaning stays even where nothing is colored. Text inside a panel is converted like any other text, including lists and code.
Jira tables to Markdown
A row that starts with double pipes is the header. Markdown tables must have a header, so a table whose first row uses single pipes is still converted, with the first row as header, and the notes say so. Rows with fewer cells are padded so the table stays valid.
A link inside a cell keeps its pipe, because the splitter reads square brackets as one piece. A cell that spans several lines in Jira is not joined. If you have HTML tables instead, HTML Table to Markdown handles those.
Macros, mentions and colors
Markdown has no table of contents macro, no color, no underline and no user lookup, so those parts are handled openly. Unknown macros such as {toc} are removed or kept as text, as you choose, and each one is counted in the macro list. Color macros lose the color and keep the words. A mention of a user becomes @jsmith text.
Underlined text, superscript and subscript are written as plain text. An opening macro that is never closed swallows the rest of the text, and the notes report it.
Going the other way
To write Markdown and paste it into Jira, use Markdown to Jira, which also lists the Markdown that Jira cannot show. If you want plain words with no syntax at all, Markdown to Text strips the Markdown this tool produces, and Rich Text to Markdown converts text copied from a web page or editor.