Atlassian Document Format Parser¶
What is ADF?¶
Atlassian Document Format (ADF) is the rich text storage format used across Atlassian products:
Confluence - Page content
Jira - Issue descriptions, comments, and rich text custom fields
ADF stores formatted content as structured JSON. This library parses that JSON into Python objects and converts it to Markdown - making Atlassian content accessible to LLMs and AI systems.
Installation¶
pip install atlas-doc-parser
Core Use Case: ADF to Markdown¶
The primary use case is extracting content from Confluence/Jira and converting it to Markdown for AI consumption.
Step 1: Get ADF JSON from Atlassian API¶
When you fetch a Confluence page or Jira issue via their REST APIs, you receive ADF JSON (See https://github.com/MacHu-GWU/atlas_doc_parser-project/releases/download/0.1.1/example.json):
[11]:
import json
import httpx
url = "https://github.com/MacHu-GWU/atlas_doc_parser-project/releases/download/0.1.1/example.json"
data = json.loads(httpx.get(url, follow_redirects=True).text)
Step 2: Parse to Object¶
[16]:
from atlas_doc_parser.api import NodeDoc
from rich import print as rprint
doc = NodeDoc.from_dict(data)
rprint(str(doc)[:1000] + "...")
NodeDoc(type='doc', version=1, content=[NodeParagraph(type='paragraph', attrs=NodeParagraphAttrs(localId='442ee6f7-e9df-4d30-9416-3a8c0021bd89'), content=[NodeText(type='text', text='This document is purposely built for creating a software to parse Atlassian Document Format JSON.', marks=OPT)], marks=OPT), NodeParagraph(type='paragraph', attrs=NodeParagraphAttrs(localId='4a20e3ed-cdde-4982-af22-edbddd6e5901'), content=[NodeText(type='text', text='This is a table of content', marks=OPT)], marks=OPT), NodeExtension(type='extension', attrs=NodeExtensionAttrs(extensionKey='toc', extensionType='com.atlassian.confluence.macro.core', parameters={'macroParams': {'style': {'value': 'none'}}, 'macroMetadata': {'macroId': {'value': '5f7acfc6-f813-486f-b4a0-38d519c0d263'}, 'schemaVersion': {'value': '1'}, 'title': 'Table of Contents'}}, text=OPT, layout='default', localId='0affa059-1fad-4b40-8896-702b7bb16ecb'), marks=OPT), NodeHeading(type='heading', attrs=NodeHeadingAttrs(level=1, localId='43c95...
Step 3: Convert to Markdown Then Give it to AI¶
[19]:
md = doc.to_markdown()
print(md)
This document is purposely built for creating a software to parse Atlassian Document Format JSON.
This is a table of content
[Extension: com.atlassian.confluence.macro.core/toc]
# Text and Paragraph
## Text and Paragraph 28d8c0
This is a simple sentence 761ec2.
This is a simple sentence 17adc1.
This is a simple sentence 9c9c4f, there is a empty line above this.
This is a simple paragraph c3f610, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph.
This is a simple paragraph 9af9a0, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph.
This is a simple paragraph ff2fa6, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, there is a empty line above this.
## Text Style and Format e0dfeb
This is a **bolded text**, do you see that?
This is a *italic text*, do you see that?
This is a underline, do you see that?
This is a ~~strike through~~, do you see that?
This is a ***~~bolded itlic strike through and underline~~***, do you see that?
This is a subscript, do you see that?
This is a superscript, do you see that?
This text has color, do you see that?
This text has background, do you see that?
Note that you can not do Text color and Background color at the same time.
This line has code `` a = 1 + 2 ``**.**
## Hyper Link
This line has titled hyperlink [Atlas Doc Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
This line has url hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
This line has inline hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
This line has card hyperlink
[https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
This line has emoji 📝 .
This line at @machu for something.
# Bullet List b2abc0
## Simple Bullet List
bullet list 1 a50f00
- item 1
- item 2
- item 3
- bullet list 2 item 1 (there is an empty line above this between this and the previous bullet list)
- bullet list 2 item 2
- bullet list 2 item 3
## Bullet List with Format
bullet list 1 944782
- this is **Alice**, *Bob*, Cathy, ~~David~~, `` Edward ``, Frank, George.
- This line has titled hyperlink [Atlas Doc Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
- This line has url hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
- This line has inline hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
## Nested Bullet List
bullet list 1 c5e045
- **item** 1
- item 2
- `` item `` 3
- [item](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) 3.1
- item 3.1.1
- item 3.1.2
- item 3.2
- item 3.2.1
- item 3.2.2
# Ordered List 639d5a
## Simple Ordered List
Ordered list 1 e7bd58
1. Alice
2. Bob
3. Cathy
1. Ordered list 2 item 1 (there is an empty line above this between this and the previous bullet list)
2. Ordered list 2 item 2
3. Ordered list 2 item 3
## Ordered List With Format
ordered list 1 fd02cb
11. this is **Alice**, *Bob*, Cathy, ~~David~~, `` Edward ``, Frank, George.
12. This line has titled hyperlink [Atlas Doc Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
13. This line has url hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
14. This line has inline hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
## Nested Ordered List
ordered list 1 eb58ef
1. Alice
2. Bob
3. Cathy
1. Cathy 1
1. Cathy 1.1
2. Cathy 1.2
2. Cathy 2
1. Cathy 2.1
2. Cathy 2.2
# Task List 4141f8
## Nested Task List
task list 1 e5461d
- [x] Do this
- [ ] And do **this**
- [ ] sub `` task `` 1
- [x] sub task 1.1
- [ ] sub ~~task~~ 1.2
- [ ] sub **task** 2
- [ ] sub task 2.1
- [x] sub task 2.2
# Code Block 3d7d7e
This is a code block
```
> Hello world
```
This is a Python code block
```python
def add_two(a, b):\n return a + b
```
# Image 75c648
This is an image
This is an image with alt text
This is an image with clickable link
[](https://www.python.org/)
This is an image with capital and clickable link
[](https://www.python.org/)
# Table 8cb9f1
## Simple Table 69b8c4
simple table 1
| **name**<br> | **age**<br> |
| --- | --- |
| Alice<br> | 20<br> |
| Bob<br> | 35<br> |
## Multiline Content Table 51e9b3
multiline content table 1
| **Col 1**<br> | **Col 2**<br> |
| --- | --- |
| key 1<br>special character \| is not markdown friendly<br> | value 1<br>- this is **Alice**, *Bob*, Cathy, ~~David~~, `` Edward ``, Frank, George.<br>- This line has titled hyperlink [Atlas Doc Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).<br>- This line has url hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)<br>- This line has inline hyperlink [https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) |
| key 2<br>special character \| is not markdown friendly<br> | value 2<br>1. Alice<br>2. Bob<br>3. Cathy<br> 1. Cathy 1<br> 1. Cathy 1.1<br> 2. Cathy 1.2<br> 2. Cathy 2<br> 1. Cathy 2.1<br> 2. Cathy 2.2 |
| key 3<br>special character \| is not markdown friendly<br> | value 3<br>- [x] Do this<br>- [ ] And do **this**<br> - [ ] sub `` task `` 1<br> - [x] sub task 1.1<br> - [ ] sub ~~task~~ 1.2<br> - [ ] sub **task** 2<br> - [ ] sub task 2.1<br> - [x] sub task 2.2 |
# Expand 0479c0
This is a expandable container
this is expand content
- bullet 1 in expand content
- bullet 2 in expand content
- bullet 3 in expand content
> Quote something here in expand content
end of expand content
# Quote 08e36f
## Simple Quote 84378f
simple quote 1
> Alice says:
>
> Just do it!
## Quote as Container b644da
quote as container 1
> This is a one line paragraph. Text may have **bold**, *italic*, underscore, ~~strike through~~, [hyperlink](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) and more.
>
> This is a bullet list
>
> - bullet 1 in quote
> - bullet 2 in quote
>
> Code block in quote
>
> Start
>
> ```python
> def mul_two(a, b):\n return a * b
> ```
>
> End
# Panel 8c4bed
This is an info
> **INFO**
>
> Info here
>
> This is a one line paragraph. Text may have **bold**, *italic*, underscore, ~~strike through~~, [hyperlink](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/) and more.
>
> This is a bullet list
>
> - bullet 1 in panel
> - bullet 2 in panel
>
> Code block in quote
>
> Start
>
> ```python
> def mul_two(a, b):\n return a * b
> ```
>
> End
This is a note
> **NOTE**
>
> Note here
This is a success
> **SUCCESS**
>
> Success here
This is a warning
> **WARNING**
>
> Warning here
This is a error
> **ERROR**
>
> Error here
This is a custom emoji
> **CUSTOM**
>
> Custom emoji info here
This is an decision
> Decision title
> decision body here
> - alice
> - bob
> - cathy
>
> This is pure text only
This is an Date
2025-01-01
This is a status
`In Progress`
This is a devider
---
## 1.1 Header 2
### 1.1.1 Header 3
[20]:
from IPython.display import display, Markdown
display(Markdown(md))
This document is purposely built for creating a software to parse Atlassian Document Format JSON.
This is a table of content
[Extension: com.atlassian.confluence.macro.core/toc]
Text and Paragraph¶
Text and Paragraph 28d8c0¶
This is a simple sentence 761ec2.
This is a simple sentence 17adc1.
This is a simple sentence 9c9c4f, there is a empty line above this.
This is a simple paragraph c3f610, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph.
This is a simple paragraph 9af9a0, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph.
This is a simple paragraph ff2fa6, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, This is a simple paragraph, there is a empty line above this.
Text Style and Format e0dfeb¶
This is a bolded text, do you see that?
This is a italic text, do you see that?
This is a underline, do you see that?
This is a [STRIKEOUT:strike through], do you see that?
This is a bolded itlic strike through and underline, do you see that?
This is a subscript, do you see that?
This is a superscript, do you see that?
This text has color, do you see that?
This text has background, do you see that?
Note that you can not do Text color and Background color at the same time.
This line has code a = 1 + 2.
Hyper Link¶
This line has titled hyperlink Atlas Doc Format.
This line has url hyperlink https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
This line has inline hyperlink https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
This line has card hyperlink
https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
This line has emoji 📝 .
This line at @machu for something.
Bullet List b2abc0¶
Simple Bullet List¶
bullet list 1 a50f00
item 1
item 2
item 3
bullet list 2 item 1 (there is an empty line above this between this and the previous bullet list)
bullet list 2 item 2
bullet list 2 item 3
Bullet List with Format¶
bullet list 1 944782
this is Alice, Bob, Cathy, [STRIKEOUT:David],
Edward, Frank, George.This line has titled hyperlink Atlas Doc Format.
This line has url hyperlink https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
This line has inline hyperlink https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
Nested Bullet List¶
bullet list 1 c5e045
item 1
item 2
item3item 3.1
item 3.1.1
item 3.1.2
item 3.2
item 3.2.1
item 3.2.2
Ordered List 639d5a¶
Simple Ordered List¶
Ordered list 1 e7bd58
Alice
Bob
Cathy
Ordered list 2 item 1 (there is an empty line above this between this and the previous bullet list)
Ordered list 2 item 2
Ordered list 2 item 3
Ordered List With Format¶
ordered list 1 fd02cb
this is Alice, Bob, Cathy, [STRIKEOUT:David],
Edward, Frank, George.This line has titled hyperlink Atlas Doc Format.
This line has url hyperlink https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
This line has inline hyperlink https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
Nested Ordered List¶
ordered list 1 eb58ef
Alice
Bob
Cathy
Cathy 1
Cathy 1.1
Cathy 1.2
Cathy 2
Cathy 2.1
Cathy 2.2
Task List 4141f8¶
Nested Task List¶
task list 1 e5461d
[x] Do this
[ ] And do this
[ ] sub
task1[x] sub task 1.1
[ ] sub [STRIKEOUT:task] 1.2
[ ] sub task 2
[ ] sub task 2.1
[x] sub task 2.2
Code Block 3d7d7e¶
This is a code block
> Hello world
This is a Python code block
def add_two(a, b):\n return a + b
Image 75c648¶
This is an image
This is an image with alt text
This is an image with clickable link
This is an image with capital and clickable link
Table 8cb9f1¶
Simple Table 69b8c4¶
simple table 1
name |
age |
|---|---|
Alice |
20 |
Bob |
35 |
Multiline Content Table 51e9b3¶
multiline content table 1
Col 1 |
Col 2 |
|---|---|
key 1special character | is not markdown friendly |
value 1- this is Alice, Bob, Cathy, [STRIKEOUT:David], |
key 2special character | is not markdown friendly |
value 21. Alice2. Bob3. Cathy 1. Cathy 1 1. Cathy 1.1 2. Cathy 1.2 2. Cathy 2 1. Cathy 2.1 2. Cathy 2.2 |
key 3special character | is not markdown friendly |
value 3- [x] Do this- [ ] And do this - [ ] sub |
Expand 0479c0¶
This is a expandable container
this is expand content
bullet 1 in expand content
bullet 2 in expand content
bullet 3 in expand content
Quote something here in expand content
end of expand content
Quote 08e36f¶
Simple Quote 84378f¶
simple quote 1
Alice says:
Just do it!
Quote as Container b644da¶
quote as container 1
This is a one line paragraph. Text may have bold, italic, underscore, [STRIKEOUT:strike through], hyperlink and more.
This is a bullet list
bullet 1 in quote
bullet 2 in quote
Code block in quote
Start
def mul_two(a, b):\n return a * bEnd
Panel 8c4bed¶
This is an info
INFO
Info here
This is a one line paragraph. Text may have bold, italic, underscore, [STRIKEOUT:strike through], hyperlink and more.
This is a bullet list
bullet 1 in panel
bullet 2 in panel
Code block in quote
Start
def mul_two(a, b):\n return a * bEnd
This is a note
NOTE
Note here
This is a success
SUCCESS
Success here
This is a warning
WARNING
Warning here
This is a error
ERROR
Error here
This is a custom emoji
CUSTOM
Custom emoji info here
This is an decision
Decision title decision body here
alice
bob
cathy
This is pure text only This is an Date
2025-01-01
This is a status
In Progress
This is a devider
1.1 Header 2¶
1.1.1 Header 3¶
[ ]: