Convert Markdown to Jira ADF (and ADF back to Markdown)

Jira Cloud’s API does not treat a rich issue description as a plain Markdown string. In Jira REST API v3, rich-text fields use Atlassian Document Format (ADF): a tree of JSON nodes describing paragraphs, headings, lists, links, code blocks, tables, and other content.

That distinction matters when a script, app, or integration starts with Markdown. Sending the text unchanged can produce a validation error or leave you with formatting that does not resemble the original document. The reliable path is to convert Markdown to an ADF document before making the request.

If you have content ready now, open the free Jira Markdown to ADF converter. It converts in both directions and runs entirely in your browser.

How do you convert Markdown to Jira ADF?

Use the converter in Markdown → ADF mode:

1. Paste or write your GitHub-flavoured Markdown in the input editor.
2. Review the generated ADF JSON and any validation message.
3. Copy the JSON into the rich-text field in your Jira API request.

The converter handles common structures including headings, paragraphs, bold and italic text, links, ordered and unordered lists, block quotes, inline code, fenced code blocks, horizontal rules, tables, and task lists. Because it produces a complete ADF document, the result has a top-level doc node, a version, and a content array rather than an isolated paragraph fragment.

The tool is useful for one-off migrations, but it is also a quick way to understand what your own integration needs to generate. Enter a small Markdown example, inspect the resulting node tree, and then test the same JSON against Jira.

Why does Jira Cloud use ADF instead of Markdown?

Markdown is compact and convenient for people to write, but its meaning depends partly on the parser. ADF represents the editor document explicitly. A paragraph is a paragraph node; bold text is text with a strong mark; a list contains list-item nodes. That structure lets Atlassian’s editor preserve richer, more predictable content across Jira and other products.

The trade-off is verbosity. This Markdown:

## Checkout error

1. Open the basket
2. Select **Pay now**

Expected: the payment form opens.

becomes a nested JSON document with heading, ordered-list, list-item, paragraph, text, and strong mark nodes. Writing that JSON by hand is possible, but it is tedious and easy to get wrong. A converter lets authors keep Markdown as the source format while the integration sends the format Jira expects.

How do you use ADF in a Jira REST API request?

After converting the Markdown, use the resulting document as the value of the relevant rich-text field. For an issue description, the shape is conceptually:

{
  "fields": {
    "summary": "Checkout button does not open payment form",
    "description": {
      "type": "doc",
      "version": 1,
      "content": []
    }
  }
}

Replace the empty content array with the content generated by the converter. Keep the complete ADF object intact; do not stringify it again inside the JSON request body.

The exact fields available depend on your Jira project, issue type, and API endpoint. Treat the converter as the formatting layer, then apply the authentication, permissions, required fields, and endpoint rules for your Jira site.

How do you convert Jira ADF back to Markdown?

The reverse direction is helpful when exporting issues, synchronising Jira with GitHub, generating release notes, or making rich descriptions editable in a text-based system.

Open the Jira Markdown and ADF converter, switch to ADF → Markdown, and paste the ADF document. The output is GitHub-flavoured Markdown that you can copy to another editor or repository.

ADF and Markdown do not have identical feature sets, so no converter can guarantee a lossless round trip for every Jira node. Standard prose, headings, links, emphasis, lists, quotes, code, and tables translate naturally. Jira-specific or unsupported rich elements may need a fallback representation or a manual decision in a production integration.

Common Markdown-to-ADF problems

Sending a Markdown string to an ADF field

A rich-text Jira field expects a document object, not the source Markdown. Convert first and send the parsed object.

Omitting the ADF document wrapper

A paragraph array by itself is not a complete document. Preserve the top-level type, version, and content properties.

Double-encoding the JSON

If the description value starts with escaped braces and quotation marks, it may have been converted into a JSON string instead of included as an object. Parse stored JSON before adding it to the request payload.

Assuming every rich node has a Markdown equivalent

Plan a policy for unsupported content when building a two-way synchronisation. Preserving readable text is often better than silently dropping a node.

Testing only simple paragraphs

Use realistic samples containing nested lists, links, code, tables, and empty lines. The edges of a document expose conversion bugs much faster than a one-sentence test.

A faster way to debug the payload

When Jira rejects a description, reduce it to the smallest ADF document that still fails. Validate the top-level document, then add headings, lists, marks, and other nodes back one at a time. The free Markdown to Jira ADF converter makes that loop quick: edit the human-readable source, inspect the JSON immediately, and copy a clean payload without sending the content anywhere.