Markdown to ADF Converter
Expert assistance for converting Markdown content to Confluence's ADF (Atlassian Document Format).
When to Use This Skill
-
Converting README.md to Confluence
-
Creating Confluence pages from Markdown documentation
-
Updating Confluence with Markdown content
-
User mentions: convert, markdown, ADF, format
-
User wants to publish Markdown to Confluence
What is ADF?
ADF (Atlassian Document Format) is Confluence's JSON-based document format. It represents content as a structured tree of nodes.
Basic ADF Structure
{ "version": 1, "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Hello world" } ] } ] }
Conversion Reference
Text Formatting
Markdown → ADF
Bold:
bold text
{ "type": "text", "text": "bold text", "marks": [{"type": "strong"}] }
Italic:
italic text
{ "type": "text", "text": "italic text", "marks": [{"type": "em"}] }
Code (inline):
code snippet
{ "type": "text", "text": "code snippet", "marks": [{"type": "code"}] }
Strikethrough:
struck text
{ "type": "text", "text": "struck text", "marks": [{"type": "strike"}] }
Underline:
<u>underlined</u>
{ "type": "text", "text": "underlined", "marks": [{"type": "underline"}] }
Combined marks:
bold italic
{ "type": "text", "text": "bold italic", "marks": [ {"type": "strong"}, {"type": "em"} ] }
Headings
Heading 1
Heading 2
Heading 3
{ "type": "heading", "attrs": {"level": 1}, "content": [ {"type": "text", "text": "Heading 1"} ] }, { "type": "heading", "attrs": {"level": 2}, "content": [ {"type": "text", "text": "Heading 2"} ] }, { "type": "heading", "attrs": {"level": 3}, "content": [ {"type": "text", "text": "Heading 3"} ] }
Note: Confluence supports heading levels 1-6.
Paragraphs
This is a paragraph.
This is another paragraph.
{ "type": "paragraph", "content": [ {"type": "text", "text": "This is a paragraph."} ] }, { "type": "paragraph", "content": [ {"type": "text", "text": "This is another paragraph."} ] }
Lists
Unordered (Bullet) List
- Item 1
- Item 2
- Nested item 2.1
- Nested item 2.2
- Item 3
{ "type": "bulletList", "content": [ { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "Item 1"}] } ] }, { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "Item 2"}] }, { "type": "bulletList", "content": [ { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "Nested item 2.1"}] } ] }, { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "Nested item 2.2"}] } ] } ] } ] }, { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "Item 3"}] } ] } ] }
Ordered (Numbered) List
- First item
- Second item
- Third item
{ "type": "orderedList", "content": [ { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "First item"}] } ] }, { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "Second item"}] } ] }, { "type": "listItem", "content": [ { "type": "paragraph", "content": [{"type": "text", "text": "Third item"}] } ] } ] }
Links
{ "type": "text", "text": "Link text", "marks": [ { "type": "link", "attrs": { "href": "https://example.com" } } ] }
Code Blocks
def hello():
print("Hello world")
```json
{
"type": "codeBlock",
"attrs": {
"language": "python"
},
"content": [
{
"type": "text",
"text": "def hello():\n print(\"Hello world\")"
}
]
}
Supported languages: javascript, python, java, go, rust, typescript, sql, bash, json, xml, html, css, and many more.
Blockquotes
> This is a quote
> Multi-line quote
{
"type": "blockquote",
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "This is a quote"}
]
},
{
"type": "paragraph",
"content": [
{"type": "text", "text": "Multi-line quote"}
]
}
]
}
Horizontal Rules
---
{
"type": "rule"
}
Tables
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
{
"type": "table",
"content": [
{
"type": "tableRow",
"content": [
{
"type": "tableHeader",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Header 1"}]
}
]
},
{
"type": "tableHeader",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Header 2"}]
}
]
},
{
"type": "tableHeader",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Header 3"}]
}
]
}
]
},
{
"type": "tableRow",
"content": [
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Cell 1"}]
}
]
},
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Cell 2"}]
}
]
},
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Cell 3"}]
}
]
}
]
},
{
"type": "tableRow",
"content": [
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Cell 4"}]
}
]
},
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Cell 5"}]
}
]
},
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Cell 6"}]
}
]
}
]
}
]
}
Images
{
"type": "mediaSingle",
"content": [
{
"type": "media",
"attrs": {
"type": "external",
"url": "https://example.com/image.png",
"alt": "Alt text"
}
}
]
}
Task Lists (Checkboxes)
- [x] Completed task
- [ ] Incomplete task
{
"type": "taskList",
"content": [
{
"type": "taskItem",
"attrs": {
"state": "DONE"
},
"content": [
{
"type": "text",
"text": "Completed task"
}
]
},
{
"type": "taskItem",
"attrs": {
"state": "TODO"
},
"content": [
{
"type": "text",
"text": "Incomplete task"
}
]
}
]
}
Confluence-Specific Extensions
Info Panel (Callout)
> ℹ️ **Info**
> This is important information
{
"type": "panel",
"attrs": {
"panelType": "info"
},
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "This is important information"}
]
}
]
}
Panel types: info
, note
, warning
, error
, success
Expand/Collapse
<details>
<summary>Click to expand</summary>
Hidden content here
</details>
{
"type": "expand",
"attrs": {
"title": "Click to expand"
},
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "Hidden content here"}
]
}
]
}
Status Badge
Status: `DONE` or `IN_PROGRESS`
{
"type": "status",
"attrs": {
"text": "DONE",
"color": "green"
}
}
Colors: neutral
, purple
, blue
, red
, yellow
, green
Mentions
@username
{
"type": "mention",
"attrs": {
"id": "user-account-id",
"text": "@username"
}
}
Emojis
:smile: :+1: :rocket:
{
"type": "emoji",
"attrs": {
"shortName": ":smile:",
"text": "😀"
}
}
Complete Example
Markdown Input
# Project Documentation
## Overview
This is a **sample project** with `code examples`.
### Features
- Feature 1
- Feature 2
- Sub-feature A
- Sub-feature B
### Installation
```bash
npm install my-package
For more info, visit our website.
Note: This is still in beta.
Command
Description
start
Start server
test
Run tests
### ADF Output
```json
{
"version": 1,
"type": "doc",
"content": [
{
"type": "heading",
"attrs": {"level": 1},
"content": [
{"type": "text", "text": "Project Documentation"}
]
},
{
"type": "heading",
"attrs": {"level": 2},
"content": [
{"type": "text", "text": "Overview"}
]
},
{
"type": "paragraph",
"content": [
{"type": "text", "text": "This is a "},
{
"type": "text",
"text": "sample project",
"marks": [{"type": "strong"}]
},
{"type": "text", "text": " with "},
{
"type": "text",
"text": "code examples",
"marks": [{"type": "code"}]
},
{"type": "text", "text": "."}
]
},
{
"type": "heading",
"attrs": {"level": 3},
"content": [
{"type": "text", "text": "Features"}
]
},
{
"type": "bulletList",
"content": [
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Feature 1"}]
}
]
},
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Feature 2"}]
},
{
"type": "bulletList",
"content": [
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Sub-feature A"}]
}
]
},
{
"type": "listItem",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Sub-feature B"}]
}
]
}
]
}
]
}
]
},
{
"type": "heading",
"attrs": {"level": 3},
"content": [
{"type": "text", "text": "Installation"}
]
},
{
"type": "codeBlock",
"attrs": {"language": "bash"},
"content": [
{
"type": "text",
"text": "npm install my-package"
}
]
},
{
"type": "paragraph",
"content": [
{"type": "text", "text": "For more info, visit "},
{
"type": "text",
"text": "our website",
"marks": [
{
"type": "link",
"attrs": {"href": "https://example.com"}
}
]
},
{"type": "text", "text": "."}
]
},
{
"type": "panel",
"attrs": {"panelType": "note"},
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Note",
"marks": [{"type": "strong"}]
},
{"type": "text", "text": ": This is still in beta."}
]
}
]
},
{
"type": "table",
"content": [
{
"type": "tableRow",
"content": [
{
"type": "tableHeader",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Command"}]
}
]
},
{
"type": "tableHeader",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Description"}]
}
]
}
]
},
{
"type": "tableRow",
"content": [
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "start",
"marks": [{"type": "code"}]
}
]
}
]
},
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Start server"}]
}
]
}
]
},
{
"type": "tableRow",
"content": [
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "test",
"marks": [{"type": "code"}]
}
]
}
]
},
{
"type": "tableCell",
"content": [
{
"type": "paragraph",
"content": [{"type": "text", "text": "Run tests"}]
}
]
}
]
}
]
}
]
}
Common Patterns
README.md to Confluence
- Extract title from first H1
- Convert sections to H2/H3
- Preserve code blocks with language tags
- Convert tables for command reference
- Add info panels for warnings/notes
- Link to external resources
API Documentation
- Endpoint sections as H2
- Parameters as tables
- Code examples with language highlighting
- Response schemas as code blocks
- Status codes as tables
Architecture Docs
- Diagrams as images
- Decision records with info panels
- Component lists as bullet lists
- Tech stack tables
Limitations and Workarounds
Not Directly Supported
Markdown feature → Workaround:
- HTML tags → Convert to ADF equivalent or plain text
- Footnotes → Use numbered references in text
- Definition lists → Use tables or headings
- Complex nested structures → Flatten or use expand sections
Confluence Enhancements
Add these Confluence-specific elements to improve readability:
- Info panels for important notes
- Expand sections for optional details
- Status badges for project status
- Task lists for checklists
- Color coding in tables
How I'll Help
When converting Markdown to ADF, I will:
- Parse the Markdown: Understand structure and content
- Convert to ADF: Build proper JSON structure
- Enhance for Confluence: Add panels, badges, etc.
- Validate: Ensure valid ADF format
- Create/Update: Use /confluence-create-page
or /confluence-update-page
- Preview: Show you what will be created
Example Interaction
You: "Convert my README.md to a Confluence page"
Me: "I'll convert your README.md to Confluence ADF format.
[Reads README.md]
I see:
- Title: "My Project"
- Sections: Overview, Installation, Usage, API Reference
- Code blocks in bash and javascript
- A table of CLI commands
- Some warnings/notes
Converting to ADF with enhancements:
- Converting code blocks with proper language tags
- Tables for command reference
- Info panels for warnings
- Links preserved
Ready to create the Confluence page. Which space should I use?"
You: "Space 123456"
Me: [Uses /confluence-create-page
with converted ADF]
"Created page 'My Project' in space 123456!
Link: https://your-domain.atlassian.net/wiki/spaces/123456/pages/..."