ADF vs HTML: How Atlassian Structures Rich Text

5 min read

If you’ve ever worked with Atlassian products like Jira or Confluence Cloud, you’ve likely come across the mysterious Atlassian Document Format (ADF) — a JSON-based schema that powers how rich text and structured content are stored and rendered.

At first glance, ADF looks nothing like HTML. Instead of <p>, <strong>, and <ul>, you’ll find nested objects like "type": "paragraph" or "marks": [{"type": "strong"}]. But ADF isn’t just another markup language — it’s a purpose-built, structured representation of content designed for modern collaborative editing.

In this post, we’ll explore how ADF differs from HTML, why Atlassian built it, and how developers can use APIs like adfapi.dev to work with it.

What Is Atlassian Document Format (ADF)?

ADF is a JSON-based document structure that describes rich text content in Atlassian Cloud products. Every page, comment, and issue description in Confluence or Jira Cloud is stored in ADF under the hood.

Here’s a simple ADF document:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Hello " },
        { "type": "text", "text": "world", "marks": [{ "type": "strong" }] }
      ]
    }
  ]
}

This produces:

Hello world

The equivalent HTML would be:

<p>Hello <strong>world</strong></p>

So why did Atlassian reinvent the wheel?

Why Atlassian Uses ADF Instead of HTML

HTML is fantastic for rendering static pages in browsers — but it has limits when used as a storage or collaboration format. Atlassian needed something:

Structured: Machines can easily parse and manipulate JSON without worrying about invalid markup.
Safe: ADF avoids XSS and script injection issues that come with storing raw HTML.
Extensible: New node types (like “decision list” or “mention”) can be added without breaking older content.
Collaborative: JSON diffs and merges are easier to handle in real-time editors like Atlassian’s Fabric editor.

In other words, ADF is built for reliability, security, and extensibility — things HTML wasn’t designed for.

ADF vs HTML: Key Differences

Feature	HTML	Atlassian Document Format (ADF)
Syntax	Text-based tags (`<p>`, `<b>`, `<a>`)	JSON objects (`"type": "paragraph"`, `"marks": [...]`)
Parsing	DOM-based, forgiving	Strict JSON schema
Security	Risk of XSS via `<script>`	No executable content allowed
Extensibility	Requires custom elements	Easily extended with new node types
Editing	Designed for rendering	Designed for programmatic editing
Storage	Human-readable markup	Machine-readable structure

Common Use Cases for ADF

Integrating with Jira or Confluence Cloud APIs
When creating or updating issues or pages, Atlassian requires the content body in ADF format.
Building Forge or Connect Apps
Apps that manipulate or display rich text in Atlassian Cloud must understand and generate ADF.
Converting Between Formats
Developers often need to convert HTML → ADF or Markdown → ADF to migrate or import content into Atlassian systems.

How to Convert HTML or Markdown to ADF

If you already have content in HTML or Markdown, converting it to ADF manually would be tedious. That’s where tools like adfapi.dev come in.

You can POST your content and get back valid ADF JSON in seconds:

curl -X POST "https://api.adfapi.dev/api/html" \
     -H "Content-Type: text/html" \
     -d "<p>Hello <strong>world</strong></p>"

Response:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Hello " },
        { "type": "text", "text": "world", "marks": [{ "type": "strong" }] }
      ]
    }
  ]
}

Final Thoughts

Atlassian Document Format (ADF) isn’t meant to replace HTML — it’s a different layer entirely, optimized for structured collaboration inside Atlassian’s ecosystem.

For developers building integrations, automation tools, or migration pipelines, understanding ADF is essential. And with services like adfapi.dev, you can bridge the gap between familiar formats like HTML or Markdown and Atlassian’s structured world of JSON.