| name | Markdown to ADF Converter |
| description | Convert Markdown content to Confluence's ADF (Atlassian Document Format) for creating and updating pages. Use when creating Confluence pages from README files, documentation, or any Markdown content. Handles headings, lists, code blocks, tables, links, and more. |
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
```python
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/..."
