Formatting Jira Descriptions: Markdown to ADF

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

Jira Markdown, the Short Answer

If you type Jira markdown into a description field expecting # headings and - bullet lists to render, you will be disappointed: Jira Cloud does not store descriptions or comments as markdown. Over its v3 REST API, Jira represents all rich text as ADF (Atlassian Document Format), a JSON tree of typed nodes. Paste raw markdown and you get literal hash marks and asterisks sitting in the text.

atlassian-cli closes that gap. When you pass markdown to --description on jira issue create or to --body on a comment, the CLI parses your markdown with a CommonMark parser and converts it to ADF before it ever reaches Jira. Headings, bold, italics, links, bullet and numbered lists, inline code, and fenced code blocks all survive into the rendered issue. You write markdown; Jira sees native formatting.

What Is ADF and Why Jira Rejects Raw Markdown

ADF is the JSON-based rich text format Jira Cloud and Confluence Cloud use in their v3 REST API. A document is an object with a type of "doc", a version of 1, and a content array of typed block nodes. Inline text lives inside those blocks and is decorated with marks. A single bold word becomes a text node carrying a strong mark; a link becomes a text node with a link mark and an href attribute.

Here is the ADF that a two-line markdown description compiles to. The markdown on the left, the JSON Jira actually stores on the right:

# Markdown you write
## Deploy checklist
- Reserve a **static IP**
- Enable Cloud NAT

# ADF that atlassian-cli sends to Jira
{
  "type": "doc",
  "version": 1,
  "content": [
    { "type": "heading", "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Deploy checklist" }] },
    { "type": "bulletList", "content": [
      { "type": "listItem", "content": [
        { "type": "paragraph", "content": [
          { "type": "text", "text": "Reserve a " },
          { "type": "text", "text": "static IP",
            "marks": [{ "type": "strong" }] }
        ] } ] },
      { "type": "listItem", "content": [
        { "type": "paragraph", "content": [
          { "type": "text", "text": "Enable Cloud NAT" }
        ] } ] }
    ] }
  ]
}

Writing that JSON by hand for every issue is exactly the kind of chore a CLI should remove. The reason Jira "rejects" your markdown is not strictness for its own sake: the API simply speaks ADF, and hand-authored ADF is verbose and easy to get wrong (nodes have strict nesting rules). Converting markdown to ADF programmatically is the reliable path.

Writing a Formatted Description in Markdown

The --description flag on jira issue create accepts markdown directly. For anything longer than a sentence, keep the body in a .md file and expand it into the flag so your editor handles the newlines:

# Author the description in a real markdown file, then create the issue
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Task \
  --summary "Ship the auth service" \
  --description "$(cat spec.md)"

For a quick inline description with structure, use bash ANSI-C quoting ($'...') so that \n becomes a real newline. Note that a normal double-quoted string does not expand \n, so $'...' or a file is the correct way to pass multi-line markdown:

# Inline multi-line markdown with $'...' so \n is a newline
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Bug \
  --summary "Login 500s under load" \
  --description $'## Steps to reproduce\n1. Hit /login 200x\n2. Watch the 500s\n\n**Impact:** blocks release'

The same flag exists on jira issue update, so you can rewrite a description after the fact without touching the web UI:

# Replace an existing description with new markdown
atlassian-cli jira issue update DEV-123 \
  --description "$(cat updated-spec.md)"

Plain text with no markdown syntax still works and is treated as a single paragraph, so you never have to think about whether a value "looks like" markdown. That backward-compatible behavior means scripts that passed plain strings keep working unchanged.

Two quoting details save time here. First, backticks inside a normal double-quoted string trigger command substitution in bash, so inline code like `--dry-run` is safest inside $'...' or a file, where backticks stay literal. Second, if you build descriptions from a template, generate the markdown file first and pass it with "$(cat file.md)" rather than escaping newlines by hand. You can set custom fields in the same command with --field 'customfield_10010={"value":"Internal"}', so a single create call carries the formatted body and any structured metadata together.

Which Markdown Maps to Which ADF Node

The converter follows CommonMark and maps each construct to its ADF equivalent. This table covers what is supported today:

A fenced code block keeps its language hint, so ```rust becomes a codeBlock with a language attribute and Jira applies the right highlighting. Ordered lists that start at a number other than 1 carry an order attribute, so 3. third renders starting at three.

Formatting Jira Comments in Markdown

Comments go through the same markdown-to-ADF path. The --body flag on jira issue comments add accepts markdown, which is handy for deploy notes, review checklists, or anything that reads better with structure:

# Add a formatted comment
atlassian-cli jira issue comments add DEV-123 \
  --body $'**Deploying now.**\n\n- Ran migrations\n- Cleared cache\n\nLogs: [dashboard](https://logs.example.com)'

# Edit an existing comment by its id
atlassian-cli jira issue comments update 10500 \
  --body "$(cat postmortem.md)"

# List comments, showing the full body instead of a preview
atlassian-cli jira issue comments list DEV-123 --full

Because the same converter powers descriptions and comments, the formatting rules you learn once apply everywhere. There is no separate comment syntax to remember.

Reading an Issue Back as Markdown

The conversion runs in both directions. When you read an issue with --format markdown, the CLI walks the stored ADF and renders it back to markdown: a summary table of the key fields followed by a ## Description section. This is ideal for piping issue context into a file, a documentation page, or a pull request body.

# Render an issue as markdown
atlassian-cli jira issue get DEV-123 --format markdown

# Save the rendered issue for a PR description or a doc
atlassian-cli jira issue get DEV-123 --format markdown > ticket.md

markdown sits alongside the other global output formats: table (the default), json, csv, yaml, and quiet. Use json when you want the raw ADF tree to inspect or transform, and markdown when you want something human-readable to paste elsewhere.

The round trip is also the quickest way to confirm a description rendered the way you intended. After a create or update, read the issue back with --format markdown and eyeball the structure, or pipe the json form to jq to inspect the exact ADF nodes Jira stored. Because the same conversion logic runs on write and on read, what you see coming back mirrors what went in.

Structural Rules the Converter Handles for You

ADF is stricter about nesting than markdown is. A naive "wrap everything in a paragraph" conversion produces documents Jira rejects or renders oddly. atlassian-cli handles the awkward cases so your markdown does not have to be perfect:

• Headings inside list items or blockquotes are not valid ADF, so they are downgraded to plain paragraphs rather than dropped.
• Nested blockquotes and blockquotes inside list items are flattened, with their content re-attached to the parent so nothing is lost.
• Inline code combined with other emphasis is normalized: ADF only lets a code mark coexist with a link, so an italicized inline-code span keeps the code and drops the conflicting mark.
• Empty input still produces a valid document (a single empty paragraph), and list items always get at least one block child, which ADF requires.

The net effect: you write ordinary markdown, and the tool produces ADF that Jira accepts on the first try. You do not have to memorize the ADF schema or debug 400 responses from the API.

How This Differs from Atlassian's Official acli

atlassian-cli is an independent, community open-source project under the MIT license. It is not Atlassian's official CLI (acli) and is not affiliated with, endorsed by, or sponsored by Atlassian. Use the official acli if you want first-party vendor support. Use atlassian-cli if you want a single free Rust binary that spans Jira, Confluence, Bitbucket, and Jira Service Management, with the markdown-to-ADF conversion described here built into its Jira commands.

For the full list of Jira verbs and flags, see the command reference, or browse the Jira CLI hub for task-focused guides. If you are automating over the API more broadly, the Jira API from the command line and Jira task management posts pick up where this one leaves off.

FAQ

Related Resources