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
json
{
"version": 1,
"type": "doc",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Hello world"
}
]
}
]
}
Conversion Reference
Text Formatting
Markdown → ADF
Bold:
markdown
**bold text**
json
{
"type": "text",
"text": "bold text",
"marks": [{"type": "strong"}]
}
Italic:
markdown
*italic text*
json
{
"type": "text",
"text": "italic text",
"marks": [{"type": "em"}]
}
Code (inline):
markdown
`code snippet`
json
{
"type": "text",
"text": "code snippet",
"marks": [{"type": "code"}]
}
Strikethrough:
markdown
~~struck text~~
json
{
"type": "text",
"text": "struck text",
"marks": [{"type": "strike"}]
}
Underline:
markdown
<u>underlined</u>
json
{
"type": "text",
"text": "underlined",
"marks": [{"type": "underline"}]
}
Combined marks:
markdown
***bold italic***
json
{
"type": "text",
"text": "bold italic",
"marks": [
{"type": "strong"},
{"type": "em"}
]
}
Headings
markdown
# Heading 1 ## Heading 2 ### Heading 3
json
{
"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
markdown
This is a paragraph. This is another paragraph.
json
{
"type": "paragraph",
"content": [
{"type": "text", "text": "This is a paragraph."}
]
},
{
"type": "paragraph",
"content": [
{"type": "text", "text": "This is another paragraph."}
]
}
Lists
Unordered (Bullet) List
markdown
- Item 1 - Item 2 - Nested item 2.1 - Nested item 2.2 - Item 3
json
{
"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
markdown
1. First item 2. Second item 3. Third item
json
{
"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
markdown
[Link text](https://example.com)
json
{
"type": "text",
"text": "Link text",
"marks": [
{
"type": "link",
"attrs": {
"href": "https://example.com"
}
}
]
}
Code Blocks
markdown
```python
def hello():
print("Hello world")
code
```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
markdown
> This is a quote > Multi-line quote
json
{
"type": "blockquote",
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "This is a quote"}
]
},
{
"type": "paragraph",
"content": [
{"type": "text", "text": "Multi-line quote"}
]
}
]
}
Horizontal Rules
markdown
---
json
{
"type": "rule"
}
Tables
markdown
| Header 1 | Header 2 | Header 3 | |----------|----------|----------| | Cell 1 | Cell 2 | Cell 3 | | Cell 4 | Cell 5 | Cell 6 |
json
{
"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
markdown
json
{
"type": "mediaSingle",
"content": [
{
"type": "media",
"attrs": {
"type": "external",
"url": "https://example.com/image.png",
"alt": "Alt text"
}
}
]
}
Task Lists (Checkboxes)
markdown
- [x] Completed task - [ ] Incomplete task
json
{
"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)
markdown
> ℹ️ **Info** > This is important information
json
{
"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
markdown
<details> <summary>Click to expand</summary> Hidden content here </details>
json
{
"type": "expand",
"attrs": {
"title": "Click to expand"
},
"content": [
{
"type": "paragraph",
"content": [
{"type": "text", "text": "Hidden content here"}
]
}
]
}
Status Badge
markdown
Status: `DONE` or `IN_PROGRESS`
json
{
"type": "status",
"attrs": {
"text": "DONE",
"color": "green"
}
}
Colors: neutral, purple, blue, red, yellow, green
Mentions
markdown
@username
json
{
"type": "mention",
"attrs": {
"id": "user-account-id",
"text": "@username"
}
}
Emojis
markdown
:smile: :+1: :rocket:
json
{
"type": "emoji",
"attrs": {
"shortName": ":smile:",
"text": "😀"
}
}
Complete Example
Markdown Input
markdown
# 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 |
code
### 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-pageor/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/..."