Converting Markdown to Atlassian Document Format (ADF): Complete Guide

5 min read

Migrating or integrating content between platforms like Jira and Confluence often means converting Markdown into Atlassian Document Format (ADF). Markdown remains the language of choice for developers, technical writers, and project managers due to its simplicity and readability. Jira and Confluence, however, rely on ADF—a JSON-based format designed for rich document representation. In this comprehensive guide, you’ll learn how to convert Markdown to ADF efficiently, compare manual vs. automated approaches, and leverage powerful APIs like adfapi.dev for seamless workflows in your Atlassian ecosystem.

What is Atlassian Document Format (ADF)?

ADF, short for Atlassian Document Format, is a JSON-based schema used by Atlassian tools (Jira, Confluence, Trello, etc.) to represent rich documents—handling text formatting, tables, mentions, images, macros, and more. Unlike Markdown, which is purely text-based, ADF captures complex, nested structures and the intricate formatting required for collaborative business environments.

Why Convert Markdown to ADF?

Migration to Jira or Confluence from Markdown-wiki based tools (like GitHub, GitLab, Notion, or legacy documentation).
Integrating developer-generated Markdown into business workflows managed in Atlassian.
Automating document ingestion for ticketing, knowledge bases, or collaborative project tracking.
Preserving formatting, structure, tables, code blocks, and other rich content across platforms.

Manual Conversion: Challenges & Limitations

While you could hand-convert Markdown to ADF, this is error-prone and inefficient for anything larger than single-line snippets.

Example: Markdown

# Project Status

* Sprint 51 Completed
* Next: Review backlog

**Lead:** Alice Johnson

Manually converted ADF (simplified):

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "Project Status" }]
    },
    {
      "type": "bulletList",
      "content": [
        { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Sprint 51 Completed" }] }] },
        { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Next: Review backlog" }] }] }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "strong", "content": [{ "type": "text", "text": "Lead:" }] },
        { "type": "text", "text": " Alice Johnson" }
      ]
    }
  ]
}

Even this trivial example demonstrates the complexity and verbosity of ADF. Manually transforming tables, code blocks, images, or embedded content is considerably more labor-intensive.

Automated Markdown to ADF: Streamlining with adfapi.dev

adfapi.dev is an API-first solution designed specifically to automate conversion from Markdown (as well as HTML and other formats) to Atlassian Document Format. It supports batch conversion, offers code libraries, and ensures that nuances like lists, headings, tables, code blocks, and rich formatting are preserved and accurately mapped.

Key Benefits:

No manual mapping of Markdown elements to ADF JSON.
Consistent, reliable conversion—ideal for bulk uploads or integrations.
Security options: use the API or the on-prem ADFKIT NuGet package, which never sends data over the wire.
Flexible workflow integration: REST API compatible with your favorite programming languages.

Sample Conversion Using adfapi.dev API

Here’s how you can convert Markdown to ADF using adfapi.dev’s REST API—perfect for automated pipelines or integrations in developer tools and CI/CD systems.

Example Markdown Input

## Release Notes

- Added OAuth2 support
- Fixed issue with ADF parsing
- Improved error logging

**Author:** John Smith

API Request (curl example)

curl -X POST https://api.adfapi.dev/api/Markdown \
  -H 'Content-Type: text/html' \
  -d '## Release Notes\n\n- Added OAuth2 support\n- Fixed issue with ADF parsing\n- Improved error logging\n\n**Author:** John Smith'

API Response (ADF JSON)

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "Release Notes" }]
    },
    {
      "type": "bulletList",
      "content": [
        { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Added OAuth2 support" }] }] },
        { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Fixed issue with ADF parsing" }] }] },
        { "type": "listItem", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Improved error logging" }] }] }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "strong", "content": [{ "type": "text", "text": "Author:" }] },
        { "type": "text", "text": " John Smith" }
      ]
    }
  ]
}

Integrating with .NET: ADFKIT NuGet Package

For enterprises and security-conscious developers, ADFAPI.dev offers ADFKIT as a NuGet package. ADFKIT enables local conversion entirely within your .NET environment, perfect for systems that require strict data control and compliance.

ADFKIT Example (C#)

using AdfKit;

string markdownContent = "## Release Notes\n\n- Added OAuth2 support\n- Fixed issue with ADF parsing\n- Improved error logging\n\n**Author:** John Smith";

var converter = new MarkdownToAdfConverter();
var adfJson = converter.ConvertMarkdown(markdownContent);

// adfJson now contains the ADF JSON representation and can be safely sent to Jira or Confluence APIs.

Features Comparison: Manual vs. Automated Conversion

Feature	Manual Conversion	Automated (adfapi.dev or ADFKIT)
Bulk Processing	Tedious, impractical	Fast, highly scalable
Complex Structures	Error-prone	Consistently accurate
Integration w/ Atlassian	Slow	API/SDK friendly
Security & Compliance	Manual checks	Optional on-prem (ADFKIT)
Developer Efficiency	Poor	Excellent

Best Practices for Markdown to ADF Conversion

Test on Sample Documents: Before bulk conversion, try several examples to verify formatting and embedded content.
Validate Output: Use the Atlassian ADF specification to check for valid JSON structures before importing.
Automate the Workflow: Integrate adfapi.dev API or ADFKIT within your codebase for seamless document migration.
Maintain Formatting Consistency: Ensure tables, links, code blocks, and lists are properly represented by reviewing output in Jira or Confluence.
Secure Sensitive Content: Use ADFKIT for local conversion if privacy concerns exist.

Conclusion

As teams increasingly blend developer-centric workflows with business applications like Jira and Confluence, reliably converting Markdown documents to ADF is critical for migration, automation, and integration. Manual conversion is plausible for the occasional short note but is unsustainable at scale.

adfapi.dev’s API accelerates migration, batch conversion, and integration in any tech stack, while ADFKIT allows developers to keep data on-prem. Both bring developer-grade automation to the Atlassian Document Format, delivering better accuracy, security, and time savings across your projects.

For more information and to get started, explore adfapi.dev’s documentation or try the instant converter for your next project. Unlock fast, secure, and code-approved ADF conversions for Jira, Confluence, and beyond.

Atlassian Document Format API Blog