Jira Markdown Syntax Guide: Modern vs. Legacy Wiki Notation

1. The Evolution of Jira Text Editing

Jira is a central tracking tool used by software development, project management, and QA groups. Over its history, the way users format text inside issues has evolved. In early versions, Atlassian created a custom markup syntax known as Jira Wiki Markup. This notation handled basic styling such as text decorations, lists, links, and code blocks.

When Atlassian launched Jira Cloud, they introduced a visual editor based on the Atlassian Document Format (ADF). This modern editor parses standard Markdown shortcuts on the fly. For instance, typing two asterisks followed by text and two more asterisks automatically bolds the text.

Despite these upgrades, legacy notation is still used in many environments. Self-hosted Jira Server and Jira Data Center setups often run older versions that do not support modern markdown. Also, Jira's REST APIs, database schemas, and integration webhooks frequently expect legacy wiki markup. This makes it necessary for developers and integrations engineers to understand both systems.

2. Modern Markdown vs. Legacy Wiki Notation

The table below provides a side-by-side comparison of standard Markdown and legacy Jira Wiki Markup for common text formatting styles:

Note the differences between these syntaxes. For example, legacy Jira uses single asterisks for bold, whereas standard Markdown uses single asterisks for italics. If you paste standard Markdown into an editor that only parses legacy markup, your italic text will render as bold and your bold text will display raw asterisks.

3. Legacy Jira Markup Reference Guide

When writing comments or formatting tickets via external tools, you will need to write legacy wiki markup. Here is a reference guide:

Lists in Wiki Markup

Create lists using asterisks for bullets and hash markers for numbered items. You can nest list elements by repeating the symbols:

* Bullet item one
* Bullet item two
** Nested bullet item

# Step one
# Step two
## Sub-step under step two

Tables in Wiki Markup

Tables are constructed using vertical bars. Double vertical bars designate header columns, while single bars designate standard content rows:

||Header Column One||Header Column Two||
|Row 1 Cell 1|Row 1 Cell 2|
|Row 2 Cell 1|Row 2 Cell 2|

Information Banners

Legacy Jira supports colored status boxes to call attention to specific notes. Wrap your text in macro tags to display a banner:

{info:title=Notice}
This is an information notification banner box.
{info}

{note}
This is a warning or alert banner box.
{note}

4. Guidelines for Formatting Bug Reports

Clear issue formatting helps engineering teams reproduce and resolve bugs faster. Below is a structured layout template recommended for bug descriptions, written in standard format:

h2. Bug Summary
Provide a brief, clear description of the issue.

h2. Steps to Reproduce
# Go to the workspace page.
# Select the text converter option.
# Paste the plain text and click convert.
# Observe the console log output.

h2. Expected Behavior
The system should parse the bullet indicators and display standard markdown dashes.

h2. Actual Behavior
The converter displays an error popup dialog box and crashes.

h2. Error Log Output
{code:javascript}
TypeError: Cannot read properties of undefined (reading 'split')
    at textToMarkdown (utils.js:14:24)
{code}

Structuring reports this way ensures that the reproduction steps, expectations, and error logs are separated and readable. Wrapping raw logs in a code block macro preserves code spacing and prevents character conversions.

5. API Integrations & Format Conversions

When integrating external development systems (such as GitHub, GitLab, or Jenkins) with Jira, managing formatting is a common task. For example, when a GitHub action posts a build summary containing standard Markdown to Jira's REST API, the text can render as unformatted strings.

Jira Cloud REST APIs expect descriptions and comments to be sent in the Atlassian Document Format (ADF), which is a JSON-based structure. Alternatively, you can configure the API request to accept raw wiki markup.

To resolve this formatting difference, developers run utility converters in their integration pipelines. These libraries parse standard Markdown text and translate it into Jira Wiki Markup or ADF JSON structures before sending the API request. Using a conversion step ensures that links, lists, and code logs render correctly in the ticket feed.

6. Common Mistakes and Parsing Conflicts

When writing formatting tags inside Jira, keep these common syntax conflicts in mind:

• Accidental Emoticon Triggers: Legacy Jira parses specific character combinations to display icons. For example, writing parentheses around the letter y (y) will render as a thumbs-up icon. This can break code paths or variable logs.
• Spacing Rules: Just like standard Markdown, legacy wiki markup requires a space after heading tags (e.g. write h2. Section, not h2.Section).
• Strikethrough Conflicts: In wiki markup, hyphens at the start of words denote strikethrough styling. If you write list items or negative numbers separated by hyphens (e.g. -5 to -10), Jira can render the text as a strikethrough block. To prevent this, wrap numbers in inline code code tags.
• Link Separator Differences: Wiki markup links use a vertical bar (|) to separate display text from the URL, whereas standard Markdown uses parentheses. Using parentheses inside legacy text areas will render raw brackets.

When setting up integrations, we recommend testing formatting outputs in a sandbox Jira project. This step ensures that the converter output renders as expected for the team.