mastering-confluence

Confluence Management Skill

Type: Project | Version: 2.2.0

Manage Confluence documentation: download pages to Markdown, upload with images, convert between formats, integrate diagrams, search with CQL.

Contents

• [Critical Constraints](#critical-constraints)
• [Quick Start](#quick-start)
• [Core Capabilities](#core-capabilities)
• [Checklists](#checklists)
• [Reference Documentation](#reference-documentation)
• [Scripts](#scripts)

Critical Constraints

DO NOT USE MCP FOR PAGE UPLOADS - Size limits apply (~10-20KB max)

# Use REST API scripts instead:
python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID

MCP tools are fine for reading pages but fail for uploading large content.

Quick Start

Upload Markdown to Confluence

# Update existing page
python3 scripts/upload_confluence_v2.py document.md --id 780369923

# Create new page
python3 scripts/upload_confluence_v2.py document.md --space DEV --parent-id 123456

# Preview first (recommended)
python3 scripts/upload_confluence_v2.py document.md --id 780369923 --dry-run

Download Confluence to Markdown

# Single page
python3 scripts/download_confluence.py 123456789

# With child pages
python3 scripts/download_confluence.py --download-children 123456789

# Multiple pages
python3 scripts/download_confluence.py 123456 456789 789012

Convert Markdown to Wiki Markup

python3 scripts/convert_markdown_to_wiki.py input.md output.wiki

Search Confluence (via MCP)

mcp__atlassian__confluence_search({
  query: 'space = "DEV" AND text ~ "API" AND created >= startOfYear()'
})

Core Capabilities

| Capability | Tool/Script | Reference | |------------|-------------|-----------| | Upload pages with images | upload_confluence_v2.py | [upload_guide](references/upload_guide.md) | | Download pages to Markdown | download_confluence.py | [download_guide](references/download_guide.md) | | Convert Markdown ↔ Wiki | convert_markdown_to_wiki.py | [conversion_guide](references/conversion_guide.md) | | Search pages (CQL) | MCP confluence_search | [cql_reference](references/cql_reference.md) | | Wiki Markup syntax | - | [wiki_markup_guide](references/wiki_markup_guide.md) | | Render Mermaid diagrams | render_mermaid.py | [image_handling](references/image_handling_best_practices.md) | | Git-to-Confluence sync | mark CLI | [mark_tool_guide](references/mark_tool_guide.md) | | Troubleshooting | - | [troubleshooting_guide](references/troubleshooting_guide.md) |

Checklists

Upload Checklist

Copy and track progress:

Upload Progress:
- [ ] Diagrams converted to PNG/SVG (if Mermaid/PlantUML present)
- [ ] All images use markdown syntax: ![alt](path)
- [ ] No raw Confluence XML in markdown
- [ ] All image files verified to exist
- [ ] Dry-run tested: `--dry-run`
- [ ] Upload executed with v2 script (not MCP)
- [ ] Page URL verified accessible

Download Checklist

Download Progress:
- [ ] Page ID obtained from Confluence URL
- [ ] Credentials configured in .env file
- [ ] Output directory specified
- [ ] --download-children flag set (if hierarchy needed)
- [ ] Download completed successfully
- [ ] Attachments downloaded to {Page}_attachments/
- [ ] Frontmatter contains correct metadata

Image Handling

Standard Workflow:

1. Convert diagrams (if Mermaid/PlantUML):

```bash # Mermaid mmdc -i diagram.mmd -o diagram.png -b transparent

# PlantUML plantuml diagram.puml -tpng ```

1. Reference in markdown (always use markdown syntax):

``markdown ![Architecture Diagram](./diagrams/architecture.png) ``

1. Upload (script handles attachments):

``bash python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID ``

Common Mistakes:

• Using raw XML: <ac:image>... - Gets HTML-escaped, appears as text
• Using MCP for uploads - Size limits cause failures
• Forgetting to convert diagrams - Code blocks don't render

Reference Documentation

| Document | Purpose | |----------|---------| | [upload_guide.md](references/upload_guide.md) | Complete upload workflow | | [download_guide.md](references/download_guide.md) | Complete download workflow | | [wiki_markup_guide.md](references/wiki_markup_guide.md) | Wiki Markup syntax reference | | [conversion_guide.md](references/conversion_guide.md) | Markdown ↔ Wiki Markup rules | | [image_handling_best_practices.md](references/image_handling_best_practices.md) | Diagrams and images | | [troubleshooting_guide.md](references/troubleshooting_guide.md) | Common errors and fixes | | [mark_tool_guide.md](references/mark_tool_guide.md) | Git-to-Confluence sync | | [confluence_storage_format.md](references/confluence_storage_format.md) | API storage format | | [cql_reference.md](references/cql_reference.md) | CQL query syntax | | [atlassian_mcp_tools.md](references/atlassian_mcp_tools.md) | MCP tool reference |

Scripts

| Script | Purpose | |--------|---------| | upload_confluence_v2.py | Upload Markdown with images (no size limits) | | download_confluence.py | Download pages to Markdown with attachments | | convert_markdown_to_wiki.py | Convert Markdown to Wiki Markup | | render_mermaid.py | Render Mermaid diagrams to PNG/SVG | | generate_mark_metadata.py | Generate mark CLI metadata headers | | confluence_auth.py | Shared authentication utilities |

Dependencies

pip install atlassian-python-api md2cf python-dotenv PyYAML mistune \
            requests markdownify beautifulsoup4

Prerequisites

Required

• Atlassian MCP Server (mcp__atlassian) with Confluence credentials

Optional

• mark CLI: Git-to-Confluence sync

``bash brew install kovetskiy/mark/mark ``

• Mermaid CLI: Diagram rendering

``bash npm install -g @mermaid-js/mermaid-cli ``

When Not to Use

• Simple page reads → Use MCP directly
• No images/diagrams, small content → MCP may work
• Jira issues → Use Jira-specific tools

Version: 2.2.0 | Last Updated: 2025-12-28