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
1. First item
2. Second item
3. 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
[Link text](https://example.com){
"type": "text",
"text": "Link text",
"marks": [
{
"type": "link",
"attrs": {
"href": "https://example.com"
}
}
]
}Code Blocks
def hello(): print("Hello world")
{
"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
npm install my-package
For more info, visit [our website](https://example.com).
> **Note**: This is still in beta.
| Command | Description |
| --- | --- |
| `start` | Start server |
| `test` | Run tests |
ADF Output
{
"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/..."