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
• Quick Start
• Core Capabilities
• Checklists
• Reference Documentation
• 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

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): # Mermaid mmdc -i diagram.mmd -o diagram.png -b transparent # PlantUML plantuml diagram.puml -tpng
2. Reference in markdown (always use markdown syntax): ![Architecture Diagram](./diagrams/architecture.png)
3. Upload (script handles attachments): 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

Scripts

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 brew install kovetskiy/mark/mark
• Mermaid CLI: Diagram rendering 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