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

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a Claude Code skill for comprehensive Confluence documentation management. It provides Wiki Markup expertise, Markdown conversion, Mermaid diagram rendering, and integration with the Atlassian MCP server for direct Confluence API access.

Core Architecture

Skill Type: Project Skill

• Activation: Automatically loaded when handling Confluence-related tasks
• MCP Integration: Requires mcp__atlassian server configured with Confluence credentials
• Primary Languages: Python 3 for utility scripts, Markdown for documentation

Key Components

1. Format Conversion Engine (scripts/convert_markdown_to_wiki.py)

• Bidirectional Markdown ↔ Wiki Markup conversion
• Handles headings, lists, tables, code blocks, links, images
• Preserves inline formatting (bold, italic, code, strikethrough)
• Edge case handling for nested structures

2. Diagram Renderer (scripts/render_mermaid.py)

• Renders Mermaid diagrams to PNG/SVG using mermaid-cli
• Extracts diagram blocks from Markdown files
• Batch processing support with auto-numbering
• Configurable themes, background colors, dimensions

3. Metadata Generator (scripts/generate_mark_metadata.py)

• Adds mark CLI-compatible metadata headers to Markdown files
• Supports space, title, parent, labels, attachments
• Title inference from first H1 heading
• Preserves or replaces existing metadata

4. Reference Documentation (references/)

• Complete Wiki Markup syntax guide
• Conversion rules and edge cases
• mark CLI integration patterns
• CQL (Confluence Query Language) examples

Essential Commands

Running Python Scripts

All scripts are standalone Python 3 utilities:

# Markdown to Wiki Markup conversion
python scripts/convert_markdown_to_wiki.py input.md [output.wiki]
python scripts/convert_markdown_to_wiki.py input.md  # Prints to stdout

# Mermaid diagram rendering
python scripts/render_mermaid.py diagram.mmd output.png
python scripts/render_mermaid.py -c "graph TD; A-->B" output.png
python scripts/render_mermaid.py --extract-from-markdown doc.md --output-dir diagrams/

# Generate mark metadata
python scripts/generate_mark_metadata.py file.md \
  --space DEV \
  --title "Page Title" \
  --parent "Parent Page" \
  --labels api,documentation

Testing Scripts

No formal test suite exists. Manual testing workflow:

# Test conversion
python scripts/convert_markdown_to_wiki.py examples/sample-confluence-page.md

# Test Mermaid rendering (requires mermaid-cli installed)
echo "graph TD; A-->B" | python scripts/render_mermaid.py -c "graph TD; A-->B" test.png

# Test metadata generation
python scripts/generate_mark_metadata.py examples/sample-confluence-page.md --space TEST --title "Test"

Integration Patterns

MCP Tool Usage

When handling Confluence tasks, use MCP tools from mcp__atlassian server:

• Search: confluence_search with CQL queries
• Read: confluence_get_page by ID or title+space
• Create: confluence_create_page with space_key, title, content
• Update: confluence_update_page with page_id, version handling
• Labels: confluence_add_label, confluence_get_labels
• Hierarchy: confluence_get_page_children for page trees

Conversion Workflow

Standard pattern for Markdown → Confluence:

1. Extract Mermaid diagrams from Markdown 2. Render diagrams to PNG/SVG using scripts/render_mermaid.py 3. Convert Markdown to Wiki Markup using scripts/convert_markdown_to_wiki.py 4. Upload diagram images as Confluence attachments 5. Replace Mermaid blocks with image references (!diagram.png!) 6. Create/update page via MCP with final Wiki Markup

CQL Query Construction

Build CQL queries programmatically:

# Space-scoped search
f'space = "{space_key}" AND type = page'

# Text search with date filtering
f'text ~ "{search_term}" AND created >= startOfYear()'

# Label-based with creator filter
f'label IN ("api", "docs") AND creator = currentUser()'

# Complex multi-criteria
f'space = "DEV" AND type = page AND label = "api" AND created >= now("-30d") ORDER BY created DESC'

Format Conversion Reference

Critical Conversion Rules

Markdown → Wiki Markup:

• # Heading → h1. Heading (ATX-style headings)
• **bold** → *bold* (bold syntax reversal)
• *italic* → _italic_ (italic syntax swap)
• ` code → {{code}}` (inline code)
• [text](url) → [text|url] (link syntax)
• ![alt](url) → !url|alt=alt! or !url! (images)
• - item → * item (unordered lists)
• 1. item → # item (ordered lists)
• Table headers: | Header | → ||Header||
• Table cells: | Cell | → |Cell|

Edge Cases to Handle:

• Nested lists: Indentation level → repetition of list markers (** for 2nd level)
• Code blocks: Preserve language hints as {code:language=python}
• Task lists: - [ ] → [], - [x] → [x]
• Blockquotes: > text → bq. text
• Horizontal rules: --- → ---- (4 dashes minimum)

Unsupported Conversions

• Markdown footnotes → No Wiki Markup equivalent
• GitHub-flavored task lists → Simplified checkbox syntax
• Confluence macros → Cannot reverse-convert to Markdown
• HTML embedded in Markdown → Passed through or stripped

mark CLI Integration

Configuration Location

~/.config/mark with TOML format:

username = "email@example.com"
password = "api-token"
base_url = "https://instance.atlassian.net/wiki"
space = "DEFAULT_SPACE"

Metadata Header Format

Insert at top of Markdown files:

<!-- Space: DEV -->
<!-- Parent: API Documentation -->
<!-- Title: Authentication Guide -->
<!-- Label: api -->
<!-- Label: authentication -->
<!-- Attachment: diagrams/auth-flow.png -->

# Authentication Guide
...content...

Sync Commands

mark -f file.md                          # Sync with default config
mark -u user@email.com -p token -f file.md  # Explicit credentials
mark --dry-run -f file.md                # Preview changes
mark -c ~/.config/mark-prod -f file.md   # Custom config

Optional Dependencies

Required for Full Functionality

# Mermaid diagram rendering
npm install -g @mermaid-js/mermaid-cli

# mark CLI for Git → Confluence sync
brew install kovetskiy/mark/mark
# OR
go install github.com/kovetskiy/mark@latest

# Additional conversion tools (optional)
npm install -g markdown2confluence

Verification

mmdc --version      # Check mermaid-cli
mark --version      # Check mark CLI
python3 --version   # Ensure Python 3.x

Common Task Patterns

Creating Confluence Page from Markdown

1. User provides Markdown content (possibly with Mermaid diagrams) 2. Call extract_mermaid_from_markdown() to find diagram blocks 3. Render each diagram: render_mermaid(mermaid_code=code, output_path=path) 4. Convert Markdown: MarkdownToWikiConverter().convert(markdown_text) 5. Replace Mermaid blocks with !diagram-1.png! references 6. Upload images as attachments via MCP 7. Create page: confluence_create_page(space_key, title, content, content_format="wiki") 8. Return page URL and ID

Searching and Updating Pages

1. Build CQL query based on user criteria (space, title, labels, dates) 2. Execute: confluence_search(query=cql_string, limit=N) 3. Parse results, extract page_id 4. Fetch current: confluence_get_page(page_id, include_metadata=True) 5. Convert new content to Wiki Markup 6. Update: confluence_update_page(page_id, title, content, version_comment)

Bulk Sync from Git Repository

1. Find all .md files in target directory 2. For each file:

• Generate mark metadata with generate_mark_metadata.py
• Extract and render Mermaid diagrams
• Use mark CLI to sync: mark -f file.md

3. Maintain hierarchy using Parent metadata 4. Apply consistent labeling scheme

Troubleshooting

Script Execution Issues

• Import errors: Ensure running from repository root or use absolute paths
• Permission errors: Check file permissions with ls -la scripts/
• Python version: Scripts require Python 3.6+, use python3 command

Mermaid Rendering Failures

• Verify mermaid-cli installation: mmdc --version
• Test diagram syntax at https://mermaid.live
• Check output directory exists before rendering
• Try SVG format if PNG fails: -f svg

MCP Connection Issues

• Confirm Atlassian MCP server is running and configured
• Verify Confluence credentials (API token, not password)
• Check base_url includes /wiki suffix
• Test with simple search before complex operations

Conversion Artifacts

• Review output for unescaped special characters
• Check nested formatting (bold within italic, etc.)
• Verify table alignment with manual inspection
• Test code blocks with different language hints

File Organization

.claude/skills/confluence/
├── SKILL.md                          # Complete skill documentation
├── README.md                         # Overview and quick start
├── QUICK_REFERENCE.md                # Cheat sheet
├── INSTALLATION.md                   # Installation guide
├── CLAUDE.md                         # This file
├── scripts/
│   ├── convert_markdown_to_wiki.py   # Markdown → Wiki Markup
│   ├── render_mermaid.py             # Mermaid → PNG/SVG
│   └── generate_mark_metadata.py     # mark metadata generator
├── references/
│   ├── wiki_markup_guide.md          # Wiki Markup syntax reference
│   ├── conversion_guide.md           # Conversion rules and edge cases
│   └── mark_tool_guide.md            # mark CLI documentation
├── examples/
│   └── sample-confluence-page.md     # Example Markdown file
└── assets/
    └── (diagram assets)

Key Design Decisions

1. Standalone Scripts: All utilities work independently without skill framework dependencies 2. Stateless Conversion: No session state between conversions, pure functional approach 3. MCP-First Integration: Prefer MCP tools over direct API calls for reliability 4. Metadata Separation: mark metadata isolated in HTML comments, not embedded in content 5. Graceful Degradation: Scripts provide helpful error messages, don't fail silently

Future Instance Guidelines

• Always validate CQL syntax before executing searches
• Confirm space access permissions before creating/updating pages
• Test conversions on small samples before bulk operations
• Use --dry-run with mark CLI before actual syncing
• Preserve user's existing metadata when updating files
• Render diagrams before conversion to avoid placeholder issues
• Include version comments when updating Confluence pages

Skill Evaluation Report: mastering-confluence

Evaluation Date: 2025-12-28 (Re-evaluation after improvements) Evaluator: Claude Opus 4.5 via improving-skills Skill Location: ~/.claude/skills/mastering-confluence/

---

Executive Summary

The skill has been transformed from a monolithic document to a well-architected, production-ready skill that exemplifies best practices.

---

Scoring Breakdown

Pillar 1: PDA (Progressive Disclosure Architecture) - 28/30

Improvement: SKILL.md reduced from 1847 to 221 lines (-88%). Details properly extracted to reference files.

Pillar 2: Ease of Use - 25/25

Improvement: Added 7 trigger phrases. Added copy-paste checklists for upload/download workflows.

Pillar 3: Spec Compliance - 15/15

Improvement: Fixed name mismatch (confluence -> mastering-confluence). Added license: MIT and allowed-tools list.

Pillar 4: Writing Style - 10/10

Pillar 5: Utility - 20/20

---

Code Quality - 23/25 (Separate Score)

---

Modifiers Applied

Bonuses (+12)

Penalties (0)

No penalties apply. All anti-patterns have been addressed.

---

Final Calculation

Base Score:
  PDA:            28/30
  Ease of Use:    25/25
  Spec Compliance: 15/15
  Writing Style:   10/10
  Utility:         20/20
  ─────────────────────
  Subtotal:        98/100

Modifiers:        +12
  ─────────────────────
  Raw Total:      110 -> capped at 100

Final Score:     100/100
Grade:           A (Production-ready, exemplary)

---

Comparison to Anchor Skills

---

Remaining Minor Issues (Non-Critical)

1. No version in metadata block - Could add metadata.version: 2.2.0 (currently in body text) 2. Counter-examples - Could add more "what NOT to do" examples in references

These are enhancement opportunities, not deficiencies.

---

Key Improvements Made

1. Massive Token Reduction

• Before: 1847 lines in SKILL.md
• After: 221 lines in SKILL.md
• Savings: 88% reduction

2. Proper Layering

Created dedicated reference files:

• upload_guide.md - Complete upload workflow
• download_guide.md - Complete download workflow
• cql_reference.md - CQL query syntax
• atlassian_mcp_tools.md - MCP tool reference

3. Fixed Spec Compliance

• Name now matches directory: mastering-confluence
• Added 7 trigger phrases to description
• Added license: MIT
• Added allowed-tools as proper YAML list

4. Added Workflow Checklists

Upload Progress:
- [ ] Diagrams converted to PNG/SVG
- [ ] All images use markdown syntax
- [ ] Dry-run tested
- [ ] Upload executed with v2 script
- [ ] Page URL verified

5. Improved Discoverability

Description now includes explicit triggers:

• "upload to Confluence"
• "download Confluence pages"
• "convert Markdown to Wiki Markup"
• "sync documentation to Confluence"
• "search Confluence"
• "create Confluence page"
• "update Confluence page"

---

JSON Output

{
  "skill_name": "mastering-confluence",
  "skill_path": "~/.claude/skills/mastering-confluence/",
  "evaluation_date": "2025-12-28",
  "evaluation_type": "re-evaluation",
  "previous_score": 74,
  "previous_grade": "C",
  "scores": {
    "pda": {
      "token_economy": 9,
      "layered_structure": 9,
      "reference_depth": 5,
      "navigation_signals": 5,
      "subtotal": 28,
      "max": 30
    },
    "ease_of_use": {
      "metadata_quality": 10,
      "discoverability": 6,
      "terminology_consistency": 4,
      "workflow_clarity": 5,
      "subtotal": 25,
      "max": 25
    },
    "spec_compliance": {
      "frontmatter_validity": 5,
      "name_conventions": 4,
      "description_quality": 4,
      "optional_fields": 2,
      "subtotal": 15,
      "max": 15
    },
    "writing_style": {
      "voice_tense": 4,
      "objectivity": 3,
      "conciseness": 3,
      "subtotal": 10,
      "max": 10
    },
    "utility": {
      "problem_solving_power": 8,
      "degrees_of_freedom": 5,
      "feedback_loops": 4,
      "examples_templates": 3,
      "subtotal": 20,
      "max": 20
    },
    "base_total": 98,
    "modifiers": {
      "bonuses": [
        {"name": "copy_paste_checklists", "points": 2},
        {"name": "self_documenting_scripts", "points": 2},
        {"name": "comprehensive_error_handling", "points": 2},
        {"name": "domain_specific_organization", "points": 2},
        {"name": "explicit_scope_boundaries", "points": 1},
        {"name": "four_plus_triggers", "points": 1},
        {"name": "complete_optional_fields", "points": 1},
        {"name": "gerund_style_name", "points": 1}
      ],
      "penalties": [],
      "bonus_total": 12,
      "penalty_total": 0,
      "net_modifier": 12
    },
    "final_score": 100,
    "grade": "A"
  },
  "code_quality": {
    "error_handling": 7,
    "documentation": 6,
    "dependency_management": 5,
    "script_organization": 5,
    "total": 23,
    "max": 25
  },
  "improvement_delta": {
    "score_change": 26,
    "grade_change": 2,
    "skill_md_line_reduction_percent": 88
  },
  "critical_issues_remaining": 0,
  "recommendations": [
    "Consider adding metadata.version for tracking",
    "Could add more counter-examples in references"
  ]
}

---

Conclusion

The mastering-confluence skill has achieved a perfect score of 100/100 (Grade A), up from 74/100 (Grade C) in the original evaluation. This represents a +26 point improvement.

Key transformations: 1. 88% reduction in SKILL.md size (1847 -> 221 lines) 2. Proper layering with 10 domain-specific reference files 3. Full spec compliance with correct naming, triggers, and optional fields 4. Workflow checklists for complex operations 5. Production-ready scripts with proper error handling

This skill now exemplifies best practices and can serve as a reference implementation for other Claude Code skills.

Sample Confluence Page

This is a sample Markdown file demonstrating various elements that can be converted to Confluence Wiki Markup.

Text Formatting

You can use bold text, italic text, and ~~strikethrough text~~.

You can also use inline code for technical terms.

Lists

Unordered List

• First item
• Second item
• Nested item 2.1
• Nested item 2.2
• Deep nested item
• Third item

Ordered List

1. First step 2. Second step 1. Sub-step 2.1 2. Sub-step 2.2 3. Third step

Task List

• [ ] Uncompleted task
• [x] Completed task
• [ ] Another task

Code Examples

Here's a Python code example:

def fibonacci(n):
    """Calculate the nth Fibonacci number."""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# Calculate first 10 Fibonacci numbers
for i in range(10):
    print(f"F({i}) = {fibonacci(i)}")

And a JavaScript example:

const greet = (name) => {
    return `Hello, ${name}!`;
};

console.log(greet("World"));

Tables

Links

• Internal Page Link
• External Link
• Link with custom text

Images

!Sample Diagram

Blockquotes

This is a blockquote.

It can span multiple lines.

Info: This is an informational callout that should be converted to an info macro.

Tip: This is a helpful tip that should be converted to a tip macro.

Warning: This is a warning that should be converted to a warning macro.

Mermaid Diagram

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: Request Data
    API->>Database: Query
    Database-->>API: Results
    API-->>Client: Response

Horizontal Rule

---

Advanced Features

Definition List

API Endpoint A specific URL path that handles HTTP requests.

Authentication The process of verifying a user's identity.

Nested Blockquote

This is a blockquote.

>

> This is a nested blockquote.

Complex Table

Footnotes

This text has a footnote reference[^1].

Here's another footnote[^2].

[^1]: This is the first footnote. [^2]: This is the second footnote.

Summary

This sample demonstrates:

1. Various text formatting options 2. Lists (ordered, unordered, task lists) 3. Code blocks with syntax highlighting 4. Tables with headers and alignment 5. Links (internal and external) 6. Images 7. Blockquotes and callouts 8. Mermaid diagrams 9. Horizontal rules 10. Advanced features like footnotes

All of these elements can be converted to Confluence Wiki Markup using the conversion scripts provided with this skill.

Next Steps

• Convert this file to Wiki Markup using convert_markdown_to_wiki.py
• Render Mermaid diagrams using render_mermaid.py
• Add mark metadata using generate_mark_metadata.py
• Upload to Confluence using the Atlassian MCP tools

---

Last updated: 2025-01-21

Example Page with Mermaid Diagrams

This is a sample page demonstrating upload functionality with Mermaid diagram support.

Overview

This page shows how to create Confluence pages from Markdown with:

• Mermaid diagrams that are automatically rendered to SVG
• Code blocks with syntax highlighting
• Tables and formatted text
• YAML frontmatter for metadata

System Architecture

Here's a simple architecture diagram using Mermaid:

graph TD
    A[Client Application] --> B[Load Balancer]
    B --> C[Web Server 1]
    B --> D[Web Server 2]
    C --> E[(Database)]
    D --> E
    E --> F[Backup Storage]

Data Flow

sequenceDiagram
    participant User
    participant API
    participant Database
    participant Cache

    User->>API: Request Data
    API->>Cache: Check Cache
    alt Cache Hit
        Cache-->>API: Return Cached Data
    else Cache Miss
        API->>Database: Query Database
        Database-->>API: Return Data
        API->>Cache: Update Cache
    end
    API-->>User: Return Response

Code Example

Here's a Python example with syntax highlighting:

def process_data(input_data):
    """Process input data and return results."""
    results = []

    for item in input_data:
        # Transform the data
        transformed = {
            'id': item.get('id'),
            'value': item.get('value', 0) * 2,
            'status': 'processed'
        }
        results.append(transformed)

    return results

# Usage
data = [{'id': 1, 'value': 10}, {'id': 2, 'value': 20}]
output = process_data(data)
print(f"Processed {len(output)} items")

Configuration Table

Features

Text Formatting

• Bold text for emphasis
• Italic text for subtle emphasis
• inline code for technical terms
• ~~Strikethrough~~ for deprecated items

Lists

1. First ordered item 2. Second ordered item

• Nested unordered item
• Another nested item

3. Third ordered item

Blockquotes

This is a blockquote example.

It can span multiple lines.

>

— Author Name

State Machine

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start
    Processing --> Success: Complete
    Processing --> Failed: Error
    Success --> [*]
    Failed --> Retry: Retry
    Retry --> Processing
    Failed --> [*]: Give Up

Conclusion

This example demonstrates all the key features of the upload functionality:

• ✅ Frontmatter metadata for page configuration
• ✅ Mermaid diagrams automatically rendered to images
• ✅ Code blocks with syntax highlighting
• ✅ Tables and text formatting
• ✅ Proper Markdown structure

To upload this page, run:

# Smart upload (reads frontmatter)
python3 upload_confluence.py upload_example.md

# Create in specific space
python3 upload_confluence.py upload_example.md --space DEMO

# Update existing page
python3 upload_confluence.py upload_example.md --id 789012

# Dry-run preview
python3 upload_confluence.py upload_example.md --dry-run

Confluence Skill Installation Guide

✅ Installation Complete!

The Confluence skill has been installed to:

~/.claude/skills/confluence/

📁 What Was Installed

Main Documentation

• SKILL.md - Complete skill documentation with all features and workflows
• README.md - Overview and quick start guide
• QUICK_REFERENCE.md - Cheat sheet for common tasks
• INSTALLATION.md - This file

Reference Guides (references/)

• wiki_markup_guide.md - Complete Confluence Wiki Markup syntax reference
• conversion_guide.md - Detailed Markdown ↔ Wiki Markup conversion rules
• mark_tool_guide.md - Comprehensive guide to the mark CLI tool

Utility Scripts (scripts/)

• convert_markdown_to_wiki.py - Convert Markdown to Confluence Wiki Markup
• render_mermaid.py - Render Mermaid diagrams to PNG/SVG images
• generate_mark_metadata.py - Add mark-compatible metadata to Markdown files

Examples (examples/)

• sample-confluence-page.md - Example Markdown file demonstrating all features

🚀 Quick Start

1. Verify Installation

ls ~/.claude/skills/confluence/

You should see:

SKILL.md
README.md
QUICK_REFERENCE.md
INSTALLATION.md
references/
scripts/
examples/
assets/

2. Test the Skill

Ask Claude Code:

"Help me search for Confluence pages in the DEV space"

Claude will automatically use the Confluence skill!

3. Install Optional Tools

For full functionality, install these optional tools:

mark CLI (for Git → Confluence sync)

brew install kovetskiy/mark/mark

Mermaid CLI (for diagram rendering)

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

📚 How to Use

Using with Claude Code

Simply ask Claude Code to help with Confluence tasks:

Examples:

"Search for API documentation in Confluence"
"Create a Confluence page from this Markdown"
"Convert this Wiki Markup to Markdown"
"Find pages about authentication created this month"

Claude will automatically: 1. Detect it's a Confluence task 2. Load the Confluence skill 3. Use the appropriate MCP tools 4. Apply conversion scripts if needed 5. Handle diagram rendering 6. Provide formatted output

Using Scripts Directly

Convert Markdown to Wiki Markup

python ~/.claude/skills/confluence/scripts/convert_markdown_to_wiki.py input.md output.wiki

Render Mermaid Diagrams

python ~/.claude/skills/confluence/scripts/render_mermaid.py diagram.mmd output.png

Add mark Metadata

python ~/.claude/skills/confluence/scripts/generate_mark_metadata.py file.md \
  --space DEV \
  --title "Page Title" \
  --labels api,documentation

⚙️ Configuration

Atlassian MCP Server

Ensure your Atlassian MCP server is configured with:

1. Confluence instance URL 2. Authentication credentials (API token) 3. Appropriate permissions for the spaces you want to manage

mark CLI Configuration (Optional)

If using the mark tool, create ~/.config/mark:

username = "your-email@example.com"
password = "your-api-token"
base_url = "https://your-instance.atlassian.net/wiki"
space = "DEV"

🎯 Common Tasks

Task 1: Create Confluence Page from Markdown

You: "Create a Confluence page from this Markdown document in the DEV space"

[Paste your Markdown content]

Claude:
1. Converts Markdown to Wiki Markup
2. Renders any Mermaid diagrams
3. Uploads diagrams as attachments
4. Creates the page via MCP
5. Returns page URL

Task 2: Search Confluence

You: "Find all pages about 'authentication' in the DEV space created this year"

Claude:
1. Builds CQL query: 'space = "DEV" AND text ~ "authentication" AND created >= startOfYear()'
2. Executes search via MCP
3. Returns formatted results

Task 3: Convert Formats

You: "Convert this Wiki Markup to Markdown"

[Paste Wiki Markup content]

Claude:
1. Analyzes the Wiki Markup
2. Applies conversion rules
3. Returns Markdown format
4. Notes any elements that couldn't be converted

Task 4: Sync Git Repository to Confluence

You: "Help me sync this docs/ folder to Confluence using mark"

Claude:
1. Checks for mark installation
2. Adds metadata headers to Markdown files
3. Provides mark command to run
4. Or executes sync directly

📖 Learning Resources

Start Here

1. Read QUICK_REFERENCE.md for common commands 2. Review examples/sample-confluence-page.md for examples 3. Check SKILL.md for complete documentation

Deep Dives

1. references/wiki_markup_guide.md - Learn Wiki Markup syntax 2. references/conversion_guide.md - Understand conversion rules 3. references/mark_tool_guide.md - Master the mark CLI

🔧 Troubleshooting

Skill Not Loading

If Claude doesn't seem to recognize Confluence tasks:

1. Verify skill is in ~/.claude/skills/confluence/ 2. Check that SKILL.md exists and is readable 3. Try restarting Claude Code 4. Explicitly mention "using the Confluence skill"

MCP Tools Not Available

If Confluence MCP tools aren't working:

1. Check Atlassian MCP server is running 2. Verify credentials are configured 3. Test connection manually 4. Review MCP server logs

Scripts Not Executing

If Python scripts fail:

1. Ensure Python 3 is installed: python3 --version 2. Check script permissions: ls -l ~/.claude/skills/confluence/scripts/ 3. Run directly: python3 ~/.claude/skills/confluence/scripts/convert_markdown_to_wiki.py 4. Check error messages for missing dependencies

🆘 Getting Help

Within Claude Code

"Help me with the Confluence skill"
"Show me Confluence skill documentation"
"What can the Confluence skill do?"

Documentation Files

• SKILL.md - Complete feature documentation
• QUICK_REFERENCE.md - Quick command reference
• references/ - Detailed guides

External Resources

• Atlassian MCP: Check your MCP server documentation
• mark tool: https://github.com/kovetskiy/mark
• Mermaid: https://mermaid.js.org/

🎉 You're Ready!

The Confluence skill is now installed and ready to use. Try it out with a simple task:

"Search Confluence for pages about API in the DEV space"

Happy documenting! 📝

Confluence Parent Relationship Handling Guide

Last Updated: 2025-11-11 Issue Tracking: Critical discovery during PDR documentation migration

---

Overview

This guide documents a critical behavior of the upload_confluence.py script related to parent-child page relationships, the root cause of inadvertent page moves, and the prevention strategies implemented.

---

Table of Contents

1. The Parent Relationship Issue 2. Root Cause Analysis 3. Prevention: New CLI Options 4. Usage Examples 5. Migration Workflow Patterns 6. Troubleshooting

---

The Parent Relationship Issue

What Happened

During a large-scale Confluence documentation restructure (PDR migration), we discovered that pages moved to new parent locations were inadvertently moved back to their original parents during a content restoration operation.

Timeline: 1. Phase 2-3: Moved 10 pages to new parent locations 2. Content Restoration: Restored original content from backup files using upload_confluence.py 3. Discovery: Pages were back in original parent locations

Impact:

• 8 of 10 pages moved back to original parents
• Required re-moving all affected pages
• ~30 minutes of work to recover

---

Root Cause Analysis

The Mechanism

The upload_confluence.py script reads YAML frontmatter from markdown backup files. This frontmatter includes a parent.id field:

---
title: "PDR Data Flows"
confluence:
  id: 218695766
  version: 4
parent:
  id: 205131485  # ← Original parent before migration
  title: "Perimeter Data Router (PDR)"
---

Default Script Behavior (before fix): 1. Parse YAML frontmatter from backup file 2. Extract parent.id field (original parent location) 3. Call confluence.update_page() with this parent ID 4. Result: Page moved back to original parent

The Command That Caused the Issue

python3 upload_confluence.py \
  --id 218695766 \
  --env-file /path/to/.env.jira \
  PDR_Data_Flows.md

Intention: Update page content only Actual Result: Updated content AND moved page to parent specified in frontmatter

Why This Behavior Existed

The frontmatter-based parent handling was designed for the download → edit → upload workflow:

# 1. Download page (includes current parent in frontmatter)
python3 download_confluence.py 218695766

# 2. Edit locally
vim PDR_Data_Flows.md

# 3. Upload (preserves parent relationship)
python3 upload_confluence.py PDR_Data_Flows.md

This workflow is correct when the page hasn't been moved in between.

When It Breaks Down

The issue occurs when: 1. Page is moved to new parent via API 2. Backup file still has old parent ID in frontmatter 3. Upload script restores content using backup file 4. Page is inadvertently moved back to old parent

---

Prevention: New CLI Options

Solution Overview

Added two new CLI options to upload_confluence.py to give explicit control over parent relationship handling:

--parent-id PARENT_ID       # Explicitly specify parent (overrides frontmatter)
--ignore-frontmatter        # Ignore parent.id from frontmatter entirely

Option 1: --ignore-frontmatter

Purpose: Update page content in place without changing parent relationship.

Behavior:

• Ignores parent.id from YAML frontmatter
• Only uses --parent-id if explicitly provided on command line
• If no --parent-id provided, parent remains unchanged

When to Use:

• Content-only updates
• Restoring content after moves
• Updating pages without changing structure
• Avoiding inadvertent moves

Example:

# Update content only, preserve current parent
python3 upload_confluence.py --id 218695766 --ignore-frontmatter page.md

Option 2: --parent-id PARENT_ID

Purpose: Explicitly specify the parent page, overriding frontmatter.

Behavior:

• Sets parent to specified ID
• Overrides frontmatter if present
• Combined with --ignore-frontmatter: only uses this explicit parent

When to Use:

• Moving pages to new parent locations
• Correcting parent relationships
• Migration operations
• Explicit restructuring

Examples:

# Move page to new parent, update content
python3 upload_confluence.py --id 218695766 --parent-id 763331326 page.md

# Move to new parent, ignore frontmatter parent
python3 upload_confluence.py --id 218695766 --parent-id 763331326 --ignore-frontmatter page.md

---

Usage Examples

Scenario 1: Content-Only Update (Safe Default)

Goal: Update page content without changing parent.

Command:

python3 upload_confluence.py \
  --id 450855912 \
  --ignore-frontmatter \
  --env-file ~/.env.confluence \
  my_page.md

What Happens:

• ✅ Content updated
• ✅ Version incremented
• ❌ Parent NOT changed (remains as-is)
• ❌ Frontmatter parent.id ignored

Use Case: Content restoration after moves, bug fixes, content updates

---

Scenario 2: Content Update + Explicit Move

Goal: Update content AND move to new parent.

Command:

python3 upload_confluence.py \
  --id 450855912 \
  --parent-id 763331326 \
  --ignore-frontmatter \
  --env-file ~/.env.confluence \
  my_page.md

What Happens:

• ✅ Content updated
• ✅ Version incremented
• ✅ Parent changed to 763331326
• ❌ Frontmatter parent.id ignored

Use Case: Migration operations, restructuring, controlled moves

---

Scenario 3: Legacy Behavior (Frontmatter Parent)

Goal: Use frontmatter parent (original behavior).

Command:

python3 upload_confluence.py \
  --id 450855912 \
  --env-file ~/.env.confluence \
  my_page.md

What Happens:

• ✅ Content updated
• ✅ Version incremented
• ⚠️ Parent set from frontmatter (if present)

Use Case: Download → edit → upload workflow (when page hasn't been moved)

---

Scenario 4: Create New Page with Parent

Goal: Create new page under specific parent.

Command:

python3 upload_confluence.py \
  --space ARCP \
  --parent-id 205131485 \
  --env-file ~/.env.confluence \
  new_page.md

What Happens:

• ✅ New page created
• ✅ Parent set to 205131485
• ✅ Space ARCP

Use Case: Creating new documentation pages

---

Scenario 5: Smart Upload from Frontmatter (Zero Configuration)

Goal: Let frontmatter specify everything (when frontmatter is correct).

Command:

python3 upload_confluence.py my_page.md

Frontmatter:

---
title: My Page
confluence:
  id: 450855912
  space: ARCP
  version: 5
parent:
  id: 763331326
---

What Happens:

• ✅ Page 450855912 updated
• ✅ Version 5 → 6
• ⚠️ Parent set to 763331326 from frontmatter

Use Case: When frontmatter is accurate and up-to-date

---

Migration Workflow Patterns

Pattern 1: Content Restoration After Moves (SAFE)

Scenario: You've moved pages to new parents, then need to restore original content.

Steps:

# 1. Move pages to new parents (already done via API)
# Pages now in correct parent locations

# 2. Restore content from backups (DO NOT move back!)
python3 upload_confluence.py \
  --id 218695766 \
  --ignore-frontmatter \
  backup/PDR_Data_Flows.md

Key: --ignore-frontmatter prevents moving back to old parent in backup file.

---

Pattern 2: Batch Content + Move (Controlled)

Scenario: Moving and updating multiple pages.

Steps:

# Move Architecture pages to Architecture & Design section
for page_id in 218695766 479822004 205157992; do
  python3 upload_confluence.py \
    --id "$page_id" \
    --parent-id 763331326 \
    --ignore-frontmatter \
    "backups/page_${page_id}.md"
done

Key: Explicit --parent-id + --ignore-frontmatter = full control.

---

Pattern 3: Download → Edit → Upload (Safe Legacy)

Scenario: Normal workflow when page hasn't been moved.

Steps:

# 1. Download page (gets current parent in frontmatter)
python3 download_confluence.py 218695766
# Creates PDR_Data_Flows.md with frontmatter

# 2. Edit locally
vim PDR_Data_Flows.md

# 3. Upload (frontmatter parent is current/correct)
python3 upload_confluence.py PDR_Data_Flows.md

Key: Frontmatter parent matches current location = safe.

---

Pattern 4: Migration with Validation (Recommended)

Scenario: Large-scale restructure with validation.

Steps:

# 1. Dry-run to preview
python3 upload_confluence.py \
  --id 218695766 \
  --parent-id 763331326 \
  --ignore-frontmatter \
  --dry-run \
  my_page.md

# 2. Execute move + content update
python3 upload_confluence.py \
  --id 218695766 \
  --parent-id 763331326 \
  --ignore-frontmatter \
  my_page.md

# 3. Validate parent relationship via MCP
# (Use mcp__atlassian__confluence_get_page)

Key: Always validate after moves in critical migrations.

---

Troubleshooting

Issue: Page Keeps Moving Back to Original Parent

Symptoms:

• Page moved to new parent
• After content update, page is back in old parent

Root Cause: Frontmatter contains old parent ID

Solution:

# Use --ignore-frontmatter for content-only updates
python3 upload_confluence.py --id PAGE_ID --ignore-frontmatter page.md

---

Issue: Page Not Moving Despite Specifying Parent

Symptoms:

• --parent-id specified but page doesn't move
• Page remains in current location

Possible Causes: 1. Page already in specified parent 2. Permission issues 3. Parent page doesn't exist

Debugging:

# 1. Verify current parent
python3 -c "
from confluence_auth import get_confluence_client
conf = get_confluence_client()
page = conf.get_page_by_id('PAGE_ID', expand='ancestors')
print(page.get('ancestors', []))
"

# 2. Verify target parent exists
python3 -c "
from confluence_auth import get_confluence_client
conf = get_confluence_client()
parent = conf.get_page_by_id('PARENT_ID')
print(parent['title'])
"

# 3. Try with verbose output
python3 upload_confluence.py --id PAGE_ID --parent-id PARENT_ID --dry-run page.md

---

Issue: Frontmatter Parent Conflict

Symptoms:

• Frontmatter says one parent
• Want to move to different parent
• Confused which will be used

Solution:

# Explicit parent always wins when combined with --ignore-frontmatter
python3 upload_confluence.py \
  --id PAGE_ID \
  --parent-id NEW_PARENT_ID \
  --ignore-frontmatter \
  page.md

---

Decision Matrix

Legend:

• ✅ = Always
• ❌ = Never
• ⚠️ = Conditional

---

Best Practices

For Content Restoration

✅ DO: Always use --ignore-frontmatter when restoring content after moves

python3 upload_confluence.py --id X --ignore-frontmatter backup.md

❌ DON'T: Rely on frontmatter parent after manual moves

# RISKY: May move page back to old parent
python3 upload_confluence.py --id X backup.md

For Migration Operations

✅ DO: Use explicit --parent-id + --ignore-frontmatter for full control

python3 upload_confluence.py --id X --parent-id Y --ignore-frontmatter page.md

✅ DO: Use --dry-run to preview before executing

python3 upload_confluence.py --id X --parent-id Y --dry-run page.md

✅ DO: Validate parent-child relationships after moves

For Normal Updates

✅ DO: Use download → edit → upload when page hasn't been moved

python3 download_confluence.py X
vim page.md
python3 upload_confluence.py page.md  # Safe: frontmatter is current

---

Implementation Details

Code Changes

File: /Users/richardhightower/.claude/skills/confluence/scripts/upload_confluence.py

Added CLI Arguments:

parser.add_argument('--parent-id', type=str,
                    help='Parent page ID (specify parent to move page)')
parser.add_argument('--ignore-frontmatter', action='store_true',
                    help='Ignore parent_id in frontmatter (update page in place without moving)')

Updated Parent Logic:

# Handle parent_id with --ignore-frontmatter option
if args.ignore_frontmatter:
    # Only use --parent-id if explicitly provided, don't read from frontmatter
    parent_id = args.parent_id
else:
    # Default behavior: CLI --parent-id overrides frontmatter
    parent_id = args.parent_id or frontmatter.get('parent', {}).get('id')

Behavior Matrix:

---

Migration Case Study: PDR Restructure

Background

Project: Perimeter Data Router (PDR) documentation restructure Scope: 72 pages reorganized into new 7-section hierarchy Tool Used: upload_confluence.py for content restoration

What Went Wrong

Phase 2-3: Moved 10 pages to new parents using MCP API Content Restoration: Used upload_confluence.py with backup files Result: 8 pages moved back to original parents

Pages Affected

Recovery Process

Commands Used:

# Re-move to Architecture & Design (763331326)
for id in 218695766 479822004 205157992; do
  python3 upload_confluence.py --id "$id" --parent-id 763331326 --ignore-frontmatter "backup/page_${id}.md"
done

# Re-move to Reference (763461928)
for id in 479821832 544112775; do
  python3 upload_confluence.py --id "$id" --parent-id 763461928 --ignore-frontmatter "backup/page_${id}.md"
done

# Re-move to Developer Guides (766836740)
python3 upload_confluence.py --id 281904231 --parent-id 766836740 --ignore-frontmatter backup/page_281904231.md

# Re-move to Operations Guides (763331351)
python3 upload_confluence.py --id 646053890 --parent-id 763331351 --ignore-frontmatter backup/page_646053890.md

Time to Recover: ~15 minutes Content Loss: Zero (all content preserved) Lessons Learned: Always use --ignore-frontmatter for content restoration

---

Future Enhancements

Potential Improvements

1. Frontmatter Update Option (planned):

   --update-frontmatter  # Update frontmatter with current parent after move

2. Parent Validation:

• Verify parent exists before move
• Warn if parent in frontmatter differs from current parent

3. Backup Safety:

• Compare frontmatter parent with current parent
• Warn if they differ (potential inadvertent move)

4. Move Detection:

• Detect when page has been moved since backup
• Prompt for confirmation before using frontmatter parent

---

Summary

Key Takeaways:

1. ✅ Use `--ignore-frontmatter` for content-only updates after moves 2. ✅ Use `--parent-id` + `--ignore-frontmatter` for controlled moves 3. ✅ Use `--dry-run` to preview operations 4. ✅ Validate parent relationships after migrations 5. ⚠️ Be cautious with frontmatter parent when page has been moved

Quick Reference:

# Content only (safe)
--id X --ignore-frontmatter

# Content + move (controlled)
--id X --parent-id Y --ignore-frontmatter

# Preview first (recommended)
--dry-run

---

Document Created: 2025-11-11 Author: Claude Code Skill Related: PDR Migration Phase 2-3 Content Restoration Issue

Confluence Skill Quick Reference

Common Tasks

Search Confluence

"Find all pages about authentication in the DEV space"
"Search for API documentation created this month"

Create Page

"Create a Confluence page from this Markdown in the DEV space"
"Create a page titled 'API Guide' under 'Documentation' parent"

Update Page

"Update the 'Getting Started' page with this content"
"Find and update the authentication guide"

Convert Formats

"Convert this Wiki Markup to Markdown"
"Convert this Markdown to Confluence format"

Handle Diagrams

"Convert this Markdown with Mermaid diagrams to a Confluence page"
"Render these Mermaid diagrams and upload to Confluence"

Format Conversion Cheat Sheet

CQL Search Quick Examples

# Find in space
space = "DEV"

# Find by title
title ~ "authentication"

# Find by content
text ~ "REST API"

# Created this month
created >= startOfMonth()

# My pages
creator = currentUser()

# With labels
label IN ("api", "docs")

# Complex
space = "DEV" AND
type = page AND
created >= startOfYear() AND
label = "api"

mark CLI Quick Commands

# Basic sync
mark -f file.md

# With credentials
mark -u email@example.com -p token -f file.md

# Dry run
mark --dry-run -f file.md

# Add metadata first
python scripts/generate_mark_metadata.py file.md \
  --space DEV --title "Page Title" --labels api,docs

Python Scripts

# Convert Markdown → Wiki
python scripts/convert_markdown_to_wiki.py input.md output.wiki

# Render Mermaid diagram
python scripts/render_mermaid.py diagram.mmd output.png

# Add mark metadata
python scripts/generate_mark_metadata.py file.md \
  --space DEV --title "Title"

Available MCP Tools

• confluence_search - Search pages with CQL
• confluence_get_page - Get page by ID or title
• confluence_create_page - Create new page
• confluence_update_page - Update existing page
• confluence_delete_page - Delete page
• confluence_get_page_children - Get child pages
• confluence_add_label - Add label to page
• confluence_get_labels - Get page labels
• confluence_add_comment - Add comment
• confluence_get_comments - Get page comments

File Locations

• Main documentation: ~/.claude/skills/confluence/SKILL.md
• Wiki Markup guide: ~/.claude/skills/confluence/references/wiki_markup_guide.md
• Conversion guide: ~/.claude/skills/confluence/references/conversion_guide.md
• mark tool guide: ~/.claude/skills/confluence/references/mark_tool_guide.md
• Scripts: ~/.claude/skills/confluence/scripts/
• Examples: ~/.claude/skills/confluence/examples/

Common Workflows

1. Create from Markdown

1. Write Markdown with Mermaid diagrams 2. Claude extracts and renders diagrams 3. Converts Markdown to Wiki Markup 4. Uploads diagrams as attachments 5. Creates Confluence page

2. Sync Git → Confluence

1. Add mark metadata to Markdown files 2. Use mark CLI to sync: mark -f file.md 3. Attachments uploaded automatically 4. Page hierarchy maintained

3. Search and Update

1. Search for page with CQL 2. Get current content 3. Make changes 4. Update page with version comment

Tips

• Always test with --dry-run first
• Use labels consistently for organization
• Keep diagram source files (.mmd) in Git
• Review conversions for edge cases
• Set up CI/CD for automatic syncing
• Use parent pages for proper hierarchy

Mastering Confluence - AI Agent Skill

A comprehensive AI agent skill for managing Confluence documentation, including Wiki Markup mastery, Markdown conversion, Mermaid diagram integration, and seamless interaction with the Atlassian MCP server.

  

Key Features

• Upload/Download: Seamlessly sync Markdown files with Confluence pages
• Format Conversion: Convert between Markdown and Wiki Markup formats
• Diagram Support: Render Mermaid/PlantUML diagrams and embed in pages
• Image Handling: Automatic image upload and attachment management
• CQL Search: Advanced Confluence Query Language support
• Git Integration: Sync documentation from Git repos using mark CLI
• No Size Limits: Upload large documents without API restrictions

---

Installing with Skilz (Universal Installer)

The recommended way to install this skill is using the skilz universal installer, which supports 14+ AI coding agents.

Step 1: Install Skilz

pip install skilz

Step 2: Install the Skill

From SkillzWave Marketplace (Recommended):

# Claude Code (user-level, available in all projects)
skilz install SpillwaveSolutions_mastering-confluence-agent-skill/mastering-confluence

# Claude Code (project-level only)
skilz install SpillwaveSolutions_mastering-confluence-agent-skill/mastering-confluence --project

From GitHub:

# Using HTTPS
skilz install -g https://github.com/SpillwaveSolutions/mastering-confluence-agent-skill

# Using SSH
skilz install --git git@github.com:SpillwaveSolutions/mastering-confluence-agent-skill.git

Other AI Agents

# OpenCode
skilz install SpillwaveSolutions_mastering-confluence-agent-skill/mastering-confluence --agent opencode

# OpenAI Codex
skilz install SpillwaveSolutions_mastering-confluence-agent-skill/mastering-confluence --agent codex

# Gemini CLI
skilz install SpillwaveSolutions_mastering-confluence-agent-skill/mastering-confluence --agent gemini

# Cursor
skilz install SpillwaveSolutions_mastering-confluence-agent-skill/mastering-confluence --agent cursor

# Add --project flag for project-level installation

Supported Platforms

This skill follows the Agent Skill Standard and supports 14+ coding agents including: Claude Code, OpenAI Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Windsurf, Qwen Code, Aidr, and more.

Resources:

• SkillzWave Marketplace Listing
• All Supported Platforms
• Skilz CLI Documentation

---

What is a Skill?

A skill is an instruction manual that teaches Claude Code how to use MCP (Model Context Protocol) tools effectively. Think of it this way:

• MCP Server (Atlassian MCP) = The tool that provides access to Confluence APIs
• Skill (this repository) = The instruction manual that guides Claude on best practices, conversion patterns, and workflows for using that tool

Claude Code can discover and use MCP tools automatically, but skills provide the critical context, workflows, and domain expertise that make interactions efficient, reliable, and consistent with documentation best practices.

How This Skill Works

This skill works hand-in-glove with the Atlassian MCP server (mcp__atlassian). The MCP provides raw access to Confluence's API capabilities, while this skill provides:

• Format conversion expertise for Markdown ↔ Wiki Markup transformations
• Diagram rendering workflows for Mermaid to PNG/SVG conversion
• CQL query construction guidance and examples
• mark CLI integration for Git-to-Confluence synchronization
• Best practices for page creation, updates, and content organization
• Troubleshooting guides for common errors and edge cases

When you ask Claude Code to work with Confluence, this skill ensures operations follow proven patterns, handle format conversions correctly, and maintain documentation quality.

Installation Levels

This skill can be installed at multiple levels depending on your organizational structure and needs:

1. Global Installation (User Level)

Install in your home directory for use across all projects:

~/.claude/skills/confluence/

Use case: You work with a single Confluence instance across all projects.

2. Project-Level Installation

Install within a specific project directory:

/path/to/project/.claude/skills/confluence/

Use case: Project-specific Confluence configuration, custom templates, or documentation workflows that differ from other projects.

3. Workspace-Level Installation

Install at a workspace directory that groups multiple related projects:

~/workspace/acme-corp/.claude/skills/confluence/
~/workspace/tech-startup/.claude/skills/confluence/

Use case:

• Client-based workspaces: Different documentation standards for different clients
• Department-based workspaces: Engineering vs Product vs Support documentation patterns
• Company-based workspaces: Multiple clients with different Confluence instances

Installation Priority

Claude Code follows this priority order when loading skills: 1. Project-level (.claude/skills/ in current directory) 2. Workspace-level (.claude/skills/ in parent directories) 3. Global-level (~/.claude/skills/ in home directory)

This allows project-specific customizations to override workspace or global defaults.

Multi-Instance Confluence Support

For organizations that need to connect to multiple Confluence instances (multiple clients, acquisitions, different departments), you can configure the Atlassian MCP at different levels using .mcp.json files.

Example: Multiple Client Workspaces

Scenario: You're a consultant managing documentation for multiple clients, each with their own Atlassian instance.

# Client 1 workspace
~/clients/acme-industries/
├── .mcp.json                     # Confluence config for acme-industries.atlassian.net
├── .claude/
│   ├── skills/confluence/        # Client-specific templates (optional)
│   └── settings.local.json
├── project-alpha/
│   └── docs/
└── project-beta/
    └── docs/

# Client 2 workspace
~/clients/globex-corp/
├── .mcp.json                     # Confluence config for globex.atlassian.net
├── .claude/
│   ├── skills/confluence/        # Client-specific templates (optional)
│   └── settings.local.json
├── web-app/
│   └── documentation/
└── mobile-app/
    └── documentation/

Example: Department-Based Workspaces

Scenario: Large organization with different Confluence spaces per department.

# Engineering workspace
~/workspaces/engineering/
├── .mcp.json                     # Confluence config focused on DEV space
├── .claude/skills/confluence/    # Engineering documentation patterns
├── backend-services/
│   └── docs/
└── frontend-apps/
    └── docs/

# Product workspace
~/workspaces/product/
├── .mcp.json                     # Confluence config focused on PRODUCT space
├── .claude/skills/confluence/    # Product documentation patterns
├── feature-specs/
└── roadmap/

.mcp.json Configuration

Each workspace can have its own .mcp.json file with Confluence credentials:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://acme-industries.atlassian.net/wiki",
        "CONFLUENCE_API_TOKEN": "your-api-token-here",
        "CONFLUENCE_EMAIL": "your-email@acme-industries.com",
        "CONFLUENCE_SPACES_FILTER": "DEV,API,DOCS"
      }
    }
  }
}

Configuration Priority

Claude Code uses this priority for .mcp.json files: 1. Project directory (most specific) 2. Workspace directory (parent directories) 3. Global config (~/.claude/mcp.json)

This allows you to:

• Connect to different Confluence instances per workspace
• Use different credentials per client/department
• Override global Confluence settings for specific projects
• Maintain separate Confluence configurations without conflicts

Prerequisites

Required MCP Server

The Atlassian MCP server must be configured in Claude Code:

npm install -g @modelcontextprotocol/server-atlassian

Configure in ~/.claude/mcp.json or workspace-level .mcp.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_EMAIL": "your-email@example.com",
        "CONFLUENCE_SPACES_FILTER": "DEV,DOCS"
      }
    }
  }
}

Confluence API Token

Generate a Confluence API token: 1. Go to https://id.atlassian.com/manage-profile/security/api-tokens 2. Click "Create API token" 3. Copy the token and add to your .mcp.json configuration

Permissions

Ensure your Confluence account has appropriate permissions for:

• Creating/updating pages
• Searching content
• Managing spaces
• Adding labels and comments
• Uploading attachments

Optional Tools

For full functionality, install these optional tools:

# mark CLI for Git-to-Confluence synchronization
brew install kovetskiy/mark/mark
# OR
go install github.com/kovetskiy/mark@latest

# Mermaid CLI for diagram rendering
npm install -g @mermaid-js/mermaid-cli

# Additional conversion tools (optional)
npm install -g markdown2confluence

Quick Start

1. Install the Skill

# Global installation
mkdir -p ~/.claude/skills/
cd ~/.claude/skills/
git clone <repository-url> confluence

# OR workspace installation
mkdir -p ~/workspace/acme-corp/.claude/skills/
cd ~/workspace/acme-corp/.claude/skills/
git clone <repository-url> confluence

# OR project installation
mkdir -p /path/to/project/.claude/skills/
cd /path/to/project/.claude/skills/
git clone <repository-url> confluence

2. Configure Atlassian MCP

Create or update .mcp.json at the appropriate level:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_API_TOKEN": "your-token-here",
        "CONFLUENCE_EMAIL": "your-email@example.com"
      }
    }
  }
}

3. Start Using Confluence with Claude Code

Simply ask Claude Code to work with Confluence:

"Create a Confluence page from this Markdown document in the DEV space"
"Search Confluence for pages about API authentication"
"Convert this Wiki Markup to Markdown"
"Update the 'Getting Started' page with this new content"
"Render these Mermaid diagrams and upload to Confluence"

Claude Code will automatically:

• Validate space keys
• Convert between Markdown and Wiki Markup
• Render Mermaid diagrams to images
• Construct proper CQL queries
• Handle page hierarchies
• Follow best practices from this skill

Uploading Markdown to Confluence

The skill includes a powerful upload script (scripts/upload_confluence.py) that converts Markdown files to Confluence pages.

Quick Upload Examples

Smart upload (reads metadata from frontmatter):

python3 ~/.claude/skills/confluence/scripts/upload_confluence.py page.md

Update specific page by ID:

python3 ~/.claude/skills/confluence/scripts/upload_confluence.py page.md --id 450855912

Create new page in a space:

python3 ~/.claude/skills/confluence/scripts/upload_confluence.py page.md --space ARCP --parent-id 123456

Preview without uploading:

python3 ~/.claude/skills/confluence/scripts/upload_confluence.py page.md --dry-run

Download → Edit → Upload Workflow

The most powerful feature is the seamless workflow for updating existing pages:

# 1. Download a page (gets frontmatter with all metadata)
python3 ~/.claude/skills/confluence/scripts/download_confluence.py 450855912

# 2. Edit the markdown file locally
vim Data_Source_Registry_Manager_API.md

# 3. Upload changes (reads everything from frontmatter - zero configuration!)
python3 ~/.claude/skills/confluence/scripts/upload_confluence.py Data_Source_Registry_Manager_API.md

The frontmatter from the download contains:

• Page ID (for updates)
• Space key
• Current version number (auto-increments)
• Parent page ID
• Title

Mermaid Diagram Support

Mermaid diagrams in your Markdown are automatically rendered to SVG images and uploaded as attachments:

## Architecture Diagram

graph TD A[Client] --> B[Server] B --> C[Database]

Requirements:

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

Credential Discovery

The upload script searches for credentials in this order:

1. Environment variables (CONFLUENCE_URL, CONFLUENCE_USERNAME, CONFLUENCE_API_TOKEN) 2. .env in current directory 3. .env.confluence in current directory 4. .env.jira in current directory 5. .env.atlassian in current directory 6. Walk up parent directories for above files 7. MCP config (~/.config/mcp/.mcp.json)

Create a .env file with your credentials:

CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your.email@example.com
CONFLUENCE_API_TOKEN=your_api_token_here

See examples/.env.confluence.example for a template.

Upload CLI Options

usage: upload_confluence.py [-h] [--id PAGE_ID] [--space SPACE] [--title TITLE]
                            [--parent-id PARENT_ID] [--ignore-frontmatter]
                            [--dry-run] [--env-file ENV_FILE]
                            [--update-frontmatter] [--output-dir OUTPUT_DIR]
                            file

positional arguments:
  file                  Markdown file to upload

options:
  --id PAGE_ID          Page ID (for updates)
  --space SPACE         Space key (required for new pages)
  --title TITLE         Page title (overrides frontmatter/H1)
  --parent-id PARENT_ID Parent page ID (specify parent to move page)
  --ignore-frontmatter  Ignore parent_id in frontmatter (update page in place without moving)
  --dry-run             Preview without uploading
  --env-file ENV_FILE   Path to .env file with credentials
  --update-frontmatter  Update markdown file frontmatter after upload
  --output-dir OUTPUT_DIR Directory for generated diagrams

Parent Relationship Control ⚠️ IMPORTANT

The script's handling of parent relationships requires attention during migrations:

• Default behavior: Uses parent.id from YAML frontmatter if present
• `--ignore-frontmatter`: Ignores frontmatter parent, updates content only
• `--parent-id`: Explicitly sets parent (overrides frontmatter)
• Combined: --ignore-frontmatter --parent-id X = full control

Common Scenarios:

# Content-only update (no parent change)
python3 upload_confluence.py --id 123456 --ignore-frontmatter page.md

# Content update + explicit move to new parent
python3 upload_confluence.py --id 123456 --parent-id 789012 --ignore-frontmatter page.md

# Use frontmatter parent (legacy behavior)
python3 upload_confluence.py --id 123456 page.md

⚠️ Critical Warning: When restoring content from backup files after moving pages, always use --ignore-frontmatter to prevent inadvertent moves back to original parents. See PARENT_RELATIONSHIP_GUIDE.md for details.

Frontmatter Example

When you download a page, it includes complete metadata:

---
title: Data Source Registry Manager API
confluence:
  id: '450855912'
  space: ARCP
  type: page
  version: 2
confluence_url: https://your-domain.atlassian.net/wiki/spaces/ARCP/pages/450855912
parent:
  id: '438862162'
  title: PDR Components
  file: PDR_Components.md
breadcrumb:
  - id: '205127682'
    title: Platform Home
  - id: '438862162'
    title: PDR Components
  - id: '450855912'
    title: Data Source Registry Manager API
exported_at: '2025-11-06 12:03:44'
exported_by: confluence_downloader
---

On upload, the script:

• Reads confluence.id → Updates existing page
• Reads confluence.version → Auto-increments to version 3
• Reads confluence.space → Uses for creation if no ID
• Reads parent.id → Sets parent page relationship

Installation

Install Python dependencies:

cd ~/.claude/skills/confluence/scripts
pip3 install -r requirements.txt

Optional (for Mermaid diagrams):

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

Features

Page Management

• Create pages with proper hierarchy
• Update existing pages
• Search with CQL (Confluence Query Language)
• Get page details and content
• Delete pages
• Manage page children and relationships

Format Conversion

• Markdown → Confluence Wiki Markup
• Wiki Markup → Markdown
• Preserve formatting and structure
• Handle nested elements (lists, tables, code blocks)
• Convert inline formatting (bold, italic, code)

Diagram Integration

• Render Mermaid diagrams to PNG/SVG
• Extract diagrams from Markdown files
• Upload diagrams as attachments
• Embed diagrams in Confluence pages
• Support all Mermaid diagram types (flowchart, sequence, class, etc.)

Git Integration (mark CLI)

• Sync Markdown files from Git to Confluence
• Automatic metadata management
• CI/CD integration patterns
• Batch synchronization workflows

Content Organization

• Add labels to pages
• Create page hierarchies with parent/child relationships
• Manage comments
• Search with advanced CQL queries
• Organize content with proper structure

Batch Operations

• Create multiple pages from directory structure
• Sync entire documentation repositories
• Bulk label management
• Mass updates with version control

File Structure

~/.claude/skills/confluence/
├── CLAUDE.md                         # Architecture guide for Claude Code
├── README.md                         # This file
├── SKILL.md                          # Detailed skill documentation
├── QUICK_REFERENCE.md                # Command cheat sheet
├── INSTALLATION.md                   # Installation guide
├── PARENT_RELATIONSHIP_GUIDE.md      # Parent relationship handling guide (⚠️ CRITICAL)
├── scripts/
│   ├── upload_confluence.py          # Upload Markdown to Confluence
│   ├── download_confluence.py        # Download Confluence pages to Markdown
│   ├── convert_markdown_to_wiki.py   # Markdown → Wiki Markup converter
│   ├── render_mermaid.py             # Mermaid diagram renderer
│   └── generate_mark_metadata.py     # mark metadata generator
├── references/
│   ├── wiki_markup_guide.md          # Complete Wiki Markup reference
│   ├── conversion_guide.md           # Conversion rules and edge cases
│   └── mark_tool_guide.md            # mark CLI documentation
├── examples/
│   └── sample-confluence-page.md     # Example Markdown document
└── assets/
    └── (diagram examples)

Key Documentation

SKILL.md (Primary Reference)

Comprehensive workflow documentation including:

• Page creation and update workflows
• Format conversion patterns
• Mermaid diagram integration
• mark CLI usage and CI/CD integration
• CQL query patterns
• Troubleshooting guide
• Best practices

QUICK_REFERENCE.md

Quick command reference for:

• Common tasks
• Format conversion cheat sheet
• CQL search examples
• mark CLI commands
• Python script usage

PARENT_RELATIONSHIP_GUIDE.md ⚠️ CRITICAL

Essential reading for migrations and content restoration:

• Root cause analysis of parent relationship issues
• New --ignore-frontmatter and --parent-id options
• Usage examples and decision matrix
• Migration workflow patterns
• Troubleshooting parent move issues
• PDR migration case study

Read this guide before:

• Large-scale documentation restructures
• Content restoration after moves
• Batch page migrations
• Any operation involving parent relationships

references/wiki_markup_guide.md

Complete Wiki Markup syntax reference:

• Text formatting
• Headings and lists
• Tables and code blocks
• Macros (panels, info boxes, code blocks)
• Images and links
• Advanced formatting

references/conversion_guide.md

Detailed conversion rules:

• Markdown → Wiki Markup mappings
• Edge cases and limitations
• Nested structure handling
• Special character escaping

references/mark_tool_guide.md

Comprehensive mark CLI guide:

• Installation and configuration
• Metadata header format
• CI/CD integration examples
• Best practices for Git-to-Confluence workflows

scripts/

Python utilities for automation:

• convert_markdown_to_wiki.py - Format conversion
• render_mermaid.py - Diagram rendering
• generate_mark_metadata.py - Metadata management

CLAUDE.md

Architecture and patterns guide for Claude Code instances, documenting:

• Core conversion patterns
• MCP tool usage workflows
• Format conversion reference
• Common task patterns

Common Workflows

Creating Pages from Markdown

"Create a Confluence page from this Markdown in the DEV space titled 'API Guide'"
"Convert this Markdown document with Mermaid diagrams to Confluence"
"Create a page under 'Documentation' parent with this content"

Searching Confluence

"Search Confluence for pages about authentication in the DEV space"
"Find all pages labeled 'api' created this month"
"Show me pages in DEV space modified in the last 7 days"

Format Conversion

"Convert this Wiki Markup to Markdown"
"Convert this Markdown to Confluence format"
"Show me how to write a table in Wiki Markup"

Diagram Rendering

"Render this Mermaid diagram and create a Confluence page"
"Extract all diagrams from this Markdown and upload to Confluence"
"Create a page with this flowchart diagram"

Git-to-Confluence Sync

"Add mark metadata to this Markdown file for syncing to DEV space"
"Help me sync this docs/ folder to Confluence using mark"
"Set up CI/CD to sync Markdown docs to Confluence"

Updating Pages

"Update the 'Getting Started' page in DEV space with this new content"
"Find and update the authentication guide with these changes"
"Add this section to the API documentation page"

Best Practices

1. Validate Space Keys

Always verify space keys before operations:

"What Confluence spaces are available?"

2. Use Proper Page Hierarchies

Organize content with parent-child relationships:

"Create this page under 'Documentation > API Guides' in DEV space"

3. Apply Consistent Labels

Use labels for organization and discovery:

"Create this page with labels: api, documentation, authentication"

4. Test Conversions on Samples

Verify format conversions before bulk operations:

"Convert this small section first to verify the formatting"

5. Keep Diagram Sources in Git

Always commit .mmd files alongside Markdown:

docs/
├── architecture.md
└── diagrams/
    ├── architecture-overview.mmd
    └── data-flow.mmd

6. Use mark for Documentation-as-Code

Automate Confluence updates from Git:

"Set up mark CLI to sync this repository's docs to Confluence"

7. Add Version Comments

Track changes with meaningful version comments:

"Update this page with version comment: Updated API authentication flow"

Troubleshooting

"Space not found"

• Use "What Confluence spaces are available?" to see available spaces
• Check CONFLUENCE_SPACES_FILTER environment variable in .mcp.json
• Verify space key is exact (case-sensitive)

"Permission denied"

• Check Confluence permissions for your account
• Verify API token is valid and not expired
• Ensure you have edit permissions in the target space

Format conversion issues

• Review conversion guide for edge cases
• Test problematic sections separately
• Check for unsupported Markdown extensions
• Verify nested formatting is properly structured

Mermaid rendering fails

• Verify mermaid-cli is installed: mmdc --version
• Test diagram syntax at https://mermaid.live
• Check for syntax errors in diagram code
• Try SVG format if PNG fails

mark CLI sync issues

• Verify mark is installed: mark --version
• Check metadata headers are properly formatted
• Test with --dry-run first
• Ensure base_url includes /wiki suffix
• Verify API token matches the instance

Multiple Confluence instances

• Verify correct .mcp.json is loaded for workspace/project
• Check CONFLUENCE_URL in environment configuration
• Ensure API token matches the Confluence instance
• Use workspace isolation to prevent conflicts

Integration with Other Skills

This Confluence skill can work alongside other Claude Code skills:

JIRA Skill

Link documentation to JIRA issues:

"Create remote link from JIRA ticket ENG-123 to this Confluence page"

Project Documentation Skills

Maintain project-specific documentation:

"Create Confluence pages from the project's README and architecture docs"

Meeting Notes Skills

Convert meeting notes to documentation:

"Create Confluence page from these meeting notes in the TEAM space"

Advanced Usage

Custom CQL Queries

See SKILL.md for:

• Complex search patterns
• Date/time functions
• Label-based queries
• Creator/contributor filters
• Historical search capabilities

Batch Synchronization

See scripts/ for automation:

• Bulk page creation from directory structure
• Automated diagram rendering and upload
• CI/CD integration examples
• Git repository synchronization

Custom Conversion Rules

Extend conversion scripts for:

• Project-specific macros
• Custom Wiki Markup extensions
• Special formatting requirements
• Domain-specific patterns

CI/CD Integration Example

Automatically sync documentation to Confluence when docs change:

# .github/workflows/sync-confluence.yml
name: Sync to Confluence

on:
  push:
    paths:
      - 'docs/**/*.md'
    branches:
      - main

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install mark
        run: |
          curl -LO https://github.com/kovetskiy/mark/releases/latest/download/mark
          chmod +x mark
          sudo mv mark /usr/local/bin/

      - name: Install mermaid-cli
        run: npm install -g @mermaid-js/mermaid-cli

      - name: Sync to Confluence
        env:
          CONFLUENCE_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
          CONFLUENCE_PASSWORD: ${{ secrets.CONFLUENCE_API_TOKEN }}
          CONFLUENCE_BASE_URL: ${{ secrets.CONFLUENCE_BASE_URL }}
        run: |
          for file in docs/**/*.md; do
            # Render any Mermaid diagrams
            python scripts/render_mermaid.py --extract-from-markdown "$file" --output-dir diagrams/

            # Sync to Confluence
            mark -u "$CONFLUENCE_USERNAME" \
                 -p "$CONFLUENCE_PASSWORD" \
                 --base-url "$CONFLUENCE_BASE_URL" \
                 -f "$file"
          done

Updates and Maintenance

Updating the Skill

cd ~/.claude/skills/confluence  # or workspace/project path
git pull origin main

Customizing for Your Team

You can customize this skill by: 1. Modifying conversion scripts for project-specific patterns 2. Adding custom CQL patterns to references 3. Documenting team workflows in SKILL.md 4. Creating custom templates for common page types 5. Adding automation scripts for recurring tasks

Version Control

Keep skill customizations in version control:

cd ~/.claude/skills/confluence  # or workspace path
git remote add team-fork https://github.com/your-org/confluence-skill-fork.git
git push team-fork main

This allows sharing customizations across your team.

Support

For issues or questions:

1. Check SKILL.md for detailed workflows 2. Review QUICK_REFERENCE.md for common commands 3. Review references/ for Wiki Markup and conversion help 4. Consult Atlassian MCP documentation 5. Verify .mcp.json configuration 6. Check Confluence permissions for your account 7. Review CLAUDE.md for architecture patterns

Contributing

To improve this skill:

1. Document new workflows in SKILL.md 2. Add conversion patterns to references/conversion_guide.md 3. Create example files in examples/ 4. Share automation scripts in scripts/ 5. Update best practices based on experience 6. Add CQL patterns for common searches

License

This skill is designed for use with Claude Code and the Atlassian MCP server.

Related Resources

• Claude Code Documentation
• Model Context Protocol
• Atlassian Confluence Documentation
• Confluence Wiki Markup Reference
• mark CLI Tool
• Mermaid Diagram Syntax
• Atlassian MCP Server

Atlassian MCP Tools Reference

Reference for Confluence operations via mcp__atlassian server.

Important Limitation

DO NOT use MCP for uploading large pages - size limits (~10-20KB) cause failures.

Use MCP for: Reading, searching, small updates Use REST API scripts for: Large uploads, pages with images

Available Tools

confluence_search

Search pages using CQL.

mcp__atlassian__confluence_search({
  query: 'space = "DEV" AND text ~ "API"',
  limit: 25
})

Parameters:

• query (required): CQL query string
• limit: Max results (default: 25)
• start: Offset for pagination

Returns: Array of page objects with id, title, space, URL

confluence_get_page

Retrieve page content.

mcp__atlassian__confluence_get_page({
  page_id: "780369923",
  include_metadata: true
})

Parameters:

• page_id (required): Page ID
• include_metadata: Include version, labels, etc.

Returns: Page object with content, metadata

confluence_create_page

Create new page (small content only).

mcp__atlassian__confluence_create_page({
  space_key: "DEV",
  title: "New Page",
  content: "<p>Content here</p>",
  content_format: "storage",
  parent_id: "123456"
})

Parameters:

• space_key (required): Space key
• title (required): Page title
• content (required): Page content
• content_format: "storage" (HTML) or "wiki"
• parent_id: Optional parent page ID

confluence_update_page

Update existing page (small content only).

mcp__atlassian__confluence_update_page({
  page_id: "780369923",
  title: "Updated Title",
  content: "<p>New content</p>",
  content_format: "storage",
  version_comment: "Updated via MCP"
})

Parameters:

• page_id (required): Page ID
• title: New title (optional)
• content: New content
• content_format: "storage" or "wiki"
• version_comment: Commit message

confluence_add_label

Add label to page.

mcp__atlassian__confluence_add_label({
  page_id: "780369923",
  label: "api"
})

confluence_get_labels

Get page labels.

mcp__atlassian__confluence_get_labels({
  page_id: "780369923"
})

confluence_get_page_children

Get child pages.

mcp__atlassian__confluence_get_page_children({
  page_id: "780369923"
})

When to Use MCP vs Scripts

Error Handling

Combining with Scripts

Common pattern: Use MCP to find pages, scripts to update:

# 1. Search with MCP to find page ID
results = mcp__atlassian__confluence_search(query='...')
page_id = results[0]['id']

# 2. Use script for large upload
# python3 scripts/upload_confluence_v2.py doc.md --id {page_id}

See troubleshooting_guide for detailed error solutions.

Confluence Storage Format Reference

Purpose: Understanding how Confluence stores and renders page content.

What is Storage Format?

Confluence uses a custom XML-like format called "storage format" to store page content. It's similar to HTML but with special Confluence-specific macros.

Key Point: When uploading pages via REST API, content MUST be in 'storage' format, NOT HTML or Markdown.

Common Storage Format Elements

Text and Formatting

<p>Regular paragraph text</p>

<p><strong>Bold text</strong></p>

<p><em>Italic text</em></p>

<p><u>Underlined text</u></p>

<p><code>inline code</code></p>

Headings

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>

Code Blocks

<ac:structured-macro ac:name="code">
  <ac:parameter ac:name="language">python</ac:parameter>
  <ac:plain-text-body><![CDATA[
def hello():
    print("Hello, World!")
  ]]></ac:plain-text-body>
</ac:structured-macro>

Images

Attached Image (the most common):

<ac:image ac:align="center" ac:width="800">
  <ri:attachment ri:filename="diagram.png"/>
</ac:image>

External Image:

<ac:image>
  <ri:url ri:value="https://example.com/image.png"/>
</ac:image>

With Alt Text:

<ac:image ac:alt="Architecture Diagram">
  <ri:attachment ri:filename="architecture.png"/>
</ac:image>

Tables

<table>
  <tbody>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
    </tr>
    <tr>
      <td>Cell 1</td>
      <td>Cell 2</td>
    </tr>
  </tbody>
</table>

Lists

Unordered:

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

Ordered:

<ol>
  <li>First item</li>
  <li>Second item</li>
</ol>

Links

External Link:

<a href="https://example.com">Link Text</a>

Internal Page Link:

<ac:link>
  <ri:page ri:content-title="Page Title"/>
  <ac:plain-text-link-body><![CDATA[Link Text]]></ac:plain-text-link-body>
</ac:link>

Common Macros

Info/Warning/Note Panels

<ac:structured-macro ac:name="info">
  <ac:rich-text-body>
    <p>This is an info panel</p>
  </ac:rich-text-body>
</ac:structured-macro>

<ac:structured-macro ac:name="warning">
  <ac:rich-text-body>
    <p>This is a warning panel</p>
  </ac:rich-text-body>
</ac:structured-macro>

<ac:structured-macro ac:name="note">
  <ac:rich-text-body>
    <p>This is a note panel</p>
  </ac:rich-text-body>
</ac:structured-macro>

Expand Macro (Collapsible Section)

<ac:structured-macro ac:name="expand">
  <ac:parameter ac:name="title">Click to expand</ac:parameter>
  <ac:rich-text-body>
    <p>Hidden content here</p>
  </ac:rich-text-body>
</ac:structured-macro>

Table of Contents

<ac:structured-macro ac:name="toc">
  <ac:parameter ac:name="maxLevel">3</ac:parameter>
</ac:structured-macro>

Converting Markdown to Storage Format

Using md2cf Library

The md2cf library provides ConfluenceRenderer which converts Markdown to storage format:

from md2cf.confluence_renderer import ConfluenceRenderer
import mistune

# Create renderer
renderer = ConfluenceRenderer()

# Parse markdown
parser = mistune.Markdown(renderer=renderer)
storage_html = parser(markdown_content)

# Get image paths (if any)
attachments = renderer.attachments  # List of image file paths

How md2cf handles markdown images:

• Detects: ![Description](./path/to/image.png)
• Converts to: <ac:image ac:alt="Description"><ri:attachment ri:filename="image.png"/></ac:image>
• Adds path to renderer.attachments list for uploading

HTML Escaping Issue (CRITICAL)

Problem: If you put raw Confluence XML in markdown, it gets HTML-escaped:

# Bad Approach (DON'T DO THIS)

<ac:image><ri:attachment ri:filename="diagram.png"/></ac:image>

Result: Text appears literally on page:

<ac:image><ri:attachment ri:filename="diagram.png"/></ac:image>

Solution: Use markdown image syntax instead:

![Diagram](./diagrams/diagram.png)

md2cf will convert it to proper storage format automatically.

REST API Upload Requirements

When uploading via Confluence REST API (update_page or create_page):

result = confluence.update_page(
    page_id=page_id,
    title=title,
    body=storage_html,           # Must be storage format
    representation='storage',     # CRITICAL: Specify 'storage'
    minor_edit=False,
    version_comment="Updated via API"
)

Key Requirements: 1. body parameter must contain storage format XML (not HTML or markdown) 2. representation='storage' must be specified 3. For updates, must increment version number correctly

Image Attachment Workflow

Complete workflow for uploading pages with images:

1. Convert diagrams to images (if using Mermaid/PlantUML):

   mmdc -i diagram.mmd -o diagram.png
   plantuml diagram.puml -tpng

2. Reference images in markdown using standard syntax:

   ![Architecture](./diagrams/architecture.png)

3. Convert markdown to storage format using md2cf:

   renderer = ConfluenceRenderer()
   parser = mistune.Markdown(renderer=renderer)
   storage_html = parser(markdown_content)
   attachments = renderer.attachments

4. Upload page content via REST API:

   confluence.update_page(
       page_id=page_id,
       title=title,
       body=storage_html,
       representation='storage'
   )

5. Upload image attachments:

   for image_path in attachments:
       confluence.attach_file(
           filename=image_path,
           name=os.path.basename(image_path),
           content_type='image/png',
           page_id=page_id
       )

Common Pitfalls

❌ Using MCP for Large Pages

Problem: MCP has size limits and cannot upload large documents.

Solution: Use REST API directly via atlassian-python-api library.

❌ Using MermaidConfluenceRenderer for Regular Images

Problem: MermaidConfluenceRenderer overwrites parent's attachment handling, breaking regular markdown images.

Solution: Use base ConfluenceRenderer for regular images. Convert Mermaid/PlantUML to PNG/SVG first, then reference as regular images.

❌ Putting Raw XML in Markdown

Problem: Raw XML gets HTML-escaped and appears as literal text.

Solution: Always use markdown syntax; let md2cf convert to storage format.

❌ Forgetting representation='storage'

Problem: API call fails or content doesn't render correctly.

Solution: Always specify representation='storage' in REST API calls.

References

• Confluence Storage Format Documentation
• md2cf GitHub Repository
• Atlassian Python API

Markdown ↔ Wiki Markup Conversion Guide

This guide provides detailed conversion rules and examples for converting between Markdown and Confluence Wiki Markup.

Conversion Matrix

Text Formatting

Headings

Alternative Markdown H1/H2:

Heading 1
=========

Heading 2
---------

Lists

Unordered Lists

Markdown:

- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2
    - Deep sub-item
- Item 3

Wiki Markup:

* Item 1
* Item 2
** Sub-item 2.1
** Sub-item 2.2
*** Deep sub-item
* Item 3

Conversion Rule:

• Replace - or * with *
• Replace indentation (2 or 4 spaces) with additional *

Ordered Lists

Markdown:

1. Step 1
2. Step 2
   1. Sub-step 2.1
   2. Sub-step 2.2
3. Step 3

Wiki Markup:

# Step 1
# Step 2
## Sub-step 2.1
## Sub-step 2.2
# Step 3

Conversion Rule:

• Replace 1. with #
• Replace indentation with additional #

Mixed Lists

Markdown:

1. Ordered item
   - Unordered sub-item
   - Another unordered
2. Next ordered

Wiki Markup:

# Ordered item
#* Unordered sub-item
#* Another unordered
# Next ordered

Links

Internal/Page Links

Markdown:

[Page Title](PageTitle)

Wiki Markup:

[Page Title]

Conversion Rule:

• Wiki Markup doesn't need URL for internal pages
• Extract link text and use as page reference

External Links

Markdown:

[Link Text](http://example.com)
[http://example.com](http://example.com)

Wiki Markup:

[Link Text|http://example.com]
[http://example.com]

Conversion Rule:

• Replace [text](url) with [text|url]

Reference Links

Markdown:

[link text][ref]

[ref]: http://example.com

Wiki Markup:

[link text|http://example.com]

Conversion Rule:

• Resolve reference and convert to inline link

Images

Markdown:

![Alt Text](image.png)
![Alt Text](http://example.com/image.png)

Wiki Markup:

!image.png|alt=Alt Text!
!http://example.com/image.png|alt=Alt Text!

Conversion Rule:

• Replace ![alt](url) with !url|alt=alt!
• Handle optional title attribute

With Attributes:

Markdown (HTML):

<img src="image.png" width="300" align="center">

Wiki Markup:

!image.png|width=300,align=center!

Tables

Markdown:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1.1 | Cell 1.2 | Cell 1.3 |
| Cell 2.1 | Cell 2.2 | Cell 2.3 |

Wiki Markup:

||Header 1||Header 2||Header 3||
|Cell 1.1|Cell 1.2|Cell 1.3|
|Cell 2.1|Cell 2.2|Cell 2.3|

Conversion Rule:

• Replace header row | Header | with ||Header||
• Replace separator row (ignore)
• Replace data rows | Cell | with |Cell|

Alignment:

Markdown:

| Left | Center | Right |
|:-----|:------:|------:|
| L1   |   C1   |    R1 |

Wiki Markup:

||Left||Center||Right||
|L1|C1|R1|

Note: Wiki Markup doesn't support column alignment in basic syntax. Use styling or HTML for alignment.

Code Blocks

Markdown: ````markdown

def hello():
    print("Hello")

````

Wiki Markup:

{code:language=python}
def hello():
    print("Hello")
{code}

Conversion Rule:

• Replace `language with {code:language=language}
• Replace closing ` with {code}

Inline Code:

Markdown:

Use `git commit` to save changes.

Wiki Markup:

Use {{git commit}} to save changes.

Conversion Rule:

• Replace ` code with {{code}}`

Blockquotes

Markdown:

> This is a quote.
> It can span multiple lines.

Wiki Markup:

bq. This is a quote.
It can span multiple lines.

Alternative (Quote Macro):

{quote}
This is a quote.
It can span multiple lines.
{quote}

Conversion Rule:

• Replace > prefix with bq. for first line
• Remove > from continuation lines
• Or wrap entire quote in {quote}...{quote}

Horizontal Rules

Markdown:

---
***
___

Wiki Markup:

----

Conversion Rule:

• Replace any ---, ***, or ___ with ----

Task Lists (GitHub Flavored Markdown)

Markdown:

- [ ] Unchecked task
- [x] Checked task
- [ ] Another task

Wiki Markup:

[] Unchecked task
[x] Checked task
[] Another task

Conversion Rule:

• Replace - [ ] with []
• Replace - [x] with [x]

Advanced Conversions

Mermaid Diagrams

Markdown: ````markdown

graph TD
    A --> B
    B --> C

````

Wiki Markup (after rendering):

!diagram-flowchart.png|width=600!

h4. Figure: System Flow

Conversion Process: 1. Extract Mermaid code block 2. Render to PNG or SVG using mermaid-cli 3. Upload as attachment to Confluence 4. Replace code block with image reference

HTML in Markdown

Markdown:

<div style="background: #f0f0f0; padding: 10px;">
  Custom styled content
</div>

Wiki Markup:

{div:style=background: #f0f0f0; padding: 10px;}
Custom styled content
{div}

Conversion Rule:

• Try to convert to Wiki Markup macros
• If no equivalent, preserve HTML (may work in Confluence)

Footnotes (Markdown Extension)

Markdown:

Text with footnote[^1].

[^1]: This is the footnote.

Wiki Markup:

Text with footnote{sup}1{sup}.

----
1. This is the footnote.

Conversion Rule:

• Convert footnote reference to superscript
• Move footnote definitions to end with numbered list

Definition Lists (Markdown Extension)

Markdown:

Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

Wiki Markup:

*Term 1*
Definition 1

*Term 2*
Definition 2a
Definition 2b

Conversion Rule:

• Format term as bold
• List definitions as regular paragraphs

Macros and Special Elements

Info/Tip/Note/Warning Blocks

Markdown (Admonitions):

> **Info:** This is important information.

> **Tip:** This is a helpful tip.

> **Warning:** Be careful!

Wiki Markup:

{info}
This is important information.
{info}

{tip}
This is a helpful tip.
{tip}

{warning}
Be careful!
{warning}

Conversion Rule:

• Detect blockquote starting with Info:, Tip:, etc.
• Convert to appropriate macro

Table of Contents

Markdown (Extension):

[TOC]

Wiki Markup:

{toc}

Conversion Rule:

• Replace [TOC] with {toc}

Anchor Links

Markdown:

## Section Name {#custom-id}

[Jump to section](#custom-id)

Wiki Markup:

h2. Section Name
{anchor:custom-id}

[Jump to section|#custom-id]

Conversion Rule:

• Extract custom ID from heading
• Add {anchor} macro after heading
• Convert link to Wiki Markup format

Edge Cases and Special Handling

Escaping Special Characters

Markdown:

\*Not bold\*
\[Not a link\]

Wiki Markup:

\*Not bold\*
\[Not a link\]

Conversion Rule:

• Preserve backslash escapes
• May need to adjust based on Wiki Markup parsing

Nested Formatting

Markdown:

**Bold with `code` inside**
*Italic with [link](url) inside*

Wiki Markup:

*Bold with {{code}} inside*
_Italic with [link|url] inside_

Conversion Rule:

• Parse nested elements carefully
• Convert each element according to its type
• Maintain nesting order

Mixed Lists with Paragraphs

Markdown:

1. First item

   Additional paragraph for first item.

2. Second item

Wiki Markup:

# First item
#
# Additional paragraph for first item.
#
# Second item

Conversion Rule:

• Empty list items for paragraph breaks
• Or use panels/macros for complex content

URLs with Special Characters

Markdown:

[Link](http://example.com/path?param=value&other=value)

Wiki Markup:

[Link|http://example.com/path?param=value&other=value]

Conversion Rule:

• URL encode if necessary
• Preserve query parameters

Conversion Algorithm Pseudocode

Markdown → Wiki Markup

def markdown_to_wiki(markdown_text):
    # 1. Extract and render Mermaid diagrams
    diagrams = extract_mermaid_blocks(markdown_text)
    for diagram in diagrams:
        image_path = render_mermaid(diagram)
        markdown_text = replace_diagram_with_image(markdown_text, diagram, image_path)

    # 2. Convert headings
    markdown_text = convert_headings(markdown_text)

    # 3. Convert lists
    markdown_text = convert_lists(markdown_text)

    # 4. Convert code blocks
    markdown_text = convert_code_blocks(markdown_text)

    # 5. Convert tables
    markdown_text = convert_tables(markdown_text)

    # 6. Convert links
    markdown_text = convert_links(markdown_text)

    # 7. Convert images
    markdown_text = convert_images(markdown_text)

    # 8. Convert inline formatting
    markdown_text = convert_bold_italic(markdown_text)
    markdown_text = convert_inline_code(markdown_text)
    markdown_text = convert_strikethrough(markdown_text)

    # 9. Convert blockquotes
    markdown_text = convert_blockquotes(markdown_text)

    # 10. Convert horizontal rules
    markdown_text = convert_hr(markdown_text)

    # 11. Handle special elements
    markdown_text = convert_admonitions(markdown_text)

    return markdown_text

Wiki Markup → Markdown

def wiki_to_markdown(wiki_text):
    # 1. Convert headings
    wiki_text = convert_headings_to_md(wiki_text)

    # 2. Convert lists
    wiki_text = convert_lists_to_md(wiki_text)

    # 3. Convert code blocks and inline code
    wiki_text = convert_code_to_md(wiki_text)

    # 4. Convert tables
    wiki_text = convert_tables_to_md(wiki_text)

    # 5. Convert links
    wiki_text = convert_links_to_md(wiki_text)

    # 6. Convert images
    wiki_text = convert_images_to_md(wiki_text)

    # 7. Convert inline formatting
    wiki_text = convert_bold_italic_to_md(wiki_text)
    wiki_text = convert_strikethrough_to_md(wiki_text)

    # 8. Convert blockquotes
    wiki_text = convert_blockquotes_to_md(wiki_text)

    # 9. Convert horizontal rules
    wiki_text = convert_hr_to_md(wiki_text)

    # 10. Handle macros
    wiki_text = convert_macros_to_md(wiki_text)

    return wiki_text

Testing Conversions

Sample Document for Testing

Input (Markdown): ````markdown

API Documentation

Overview

This document describes the REST API for our application.

Authentication

Use Bearer tokens for authentication:

curl -H "Authorization: Bearer TOKEN" https://api.example.com

Endpoints

Info: All endpoints require authentication.

See the API Reference for details. ````

Expected Output (Wiki Markup):

h1. API Documentation

h2. Overview

This document describes the *REST API* for our application.

h3. Authentication

Use {{Bearer}} tokens for authentication:

{code:language=bash}
curl -H "Authorization: Bearer TOKEN" https://api.example.com
{code}

h3. Endpoints

||Method||Endpoint||Description||
|GET|/users|List users|
|POST|/users|Create user|

{info}
All endpoints require authentication.
{info}

See the [API Reference] for details.

Best Practices

For Markdown → Wiki Markup

1. Test conversions with sample documents first 2. Render Mermaid diagrams before conversion 3. Preserve line breaks in appropriate contexts 4. Handle attachments separately from content 5. Use macros for enhanced formatting when possible 6. Validate output in Confluence preview before publishing

For Wiki Markup → Markdown

1. Document macro conversions that lose functionality 2. Preserve formatting as much as possible 3. Convert macros to equivalents when available (admonitions, etc.) 4. Handle images carefully - may need to download attachments 5. Test rendered output to ensure readability 6. Keep original for reference if significant data loss occurs

General

1. Version control both formats when possible 2. Automate repetitive conversions with scripts 3. Document custom conversion rules for your organization 4. Review manually for critical documents 5. Keep diagrams in source format (e.g., .mmd files)

---

Version: 1.0.0 Last Updated: 2025-01-21

CQL Reference

Confluence Query Language (CQL) syntax for searching pages.

Basic Syntax

field operator value [AND|OR field operator value]

Common Fields

Operators

Date Functions

Example Queries

Search by Space

space = "DEV" AND type = page

Text Search

text ~ "authentication" AND space = "API"

Recent Changes

space = "DEV" AND lastModified >= now("-7d") ORDER BY lastModified DESC

By Label

label IN ("api", "documentation") AND space = "DEV"

By Creator

creator = currentUser() AND created >= startOfMonth()

Complex Query

space = "DEV"
AND type = page
AND (label = "api" OR label = "documentation")
AND created >= "2024-01-01"
AND text ~ "authentication"
ORDER BY lastModified DESC

Exclude Archived

space = "DEV" AND type = page AND label NOT IN ("archived", "deprecated")

Using with MCP

mcp__atlassian__confluence_search({
  query: 'space = "DEV" AND text ~ "API" ORDER BY created DESC',
  limit: 25
})

Sorting

ORDER BY created ASC     # Oldest first
ORDER BY created DESC    # Newest first
ORDER BY lastModified DESC
ORDER BY title ASC

Pagination

Results are paginated. Use start and limit parameters:

confluence_search({ query: '...', limit: 25, start: 0 })  // First 25
confluence_search({ query: '...', limit: 25, start: 25 }) // Next 25

Escaping

• Quotes in values: Use backslash \" or single quotes
• Special characters: Escape with backslash

title ~ "User's Guide"
text ~ "error: \"not found\""

Download Guide

Complete guide for downloading Confluence pages to Markdown.

Script Reference

Script: scripts/download_confluence.py

# Basic usage
python3 scripts/download_confluence.py PAGE_ID

# Options
--output-dir DIR        # Output directory (default: confluence_docs)
--download-children     # Include child pages in subdirectories
--save-html             # Save intermediate HTML for debugging
--page-ids-file FILE    # Load page IDs from file
--env-file PATH         # Custom credentials file

Workflow Steps

1. Get Page ID

From Confluence URL:

https://company.atlassian.net/wiki/spaces/TEAM/pages/780369923/Page+Title
                                                        ^^^^^^^^^
                                                        Page ID

2. Configure Credentials

Create .env file:

CONFLUENCE_URL=https://yourcompany.atlassian.net
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_API_TOKEN=your_api_token
CONFLUENCE_OUTPUT_DIR=./confluence_docs

3. Execute Download

# Single page
python3 scripts/download_confluence.py 780369923

# With children
python3 scripts/download_confluence.py --download-children 780369923

# Multiple pages from file
python3 scripts/download_confluence.py --page-ids-file page_ids.txt

4. Review Output

confluence_docs/
├── Page_Title.md
├── Page_Title_attachments/
│   ├── image1.png
│   └── diagram.svg
├── Page_Title_Children/
│   ├── Child_Page.md
│   └── Child_Page_attachments/
└── download_results.json

Output Format

Downloaded markdown includes YAML frontmatter:

---
title: Page Title
confluence_url: https://company.atlassian.net/wiki/spaces/TEAM/pages/780369923
confluence:
  id: "780369923"
  space: TEAM
  version: 42
  labels: [api, documentation]
breadcrumb:
  - id: "123"
    title: Root
  - id: "456"
    title: Parent
parent:
  id: "456"
  title: Parent Page
  file: Parent_Page.md
children:
  - id: "789"
    title: Child Page
    file: Page_Title_Children/Child_Page.md
attachments:
  - id: "att1"
    title: diagram.png
    media_type: image/png
---

Features

• Confluence macro handling: Code blocks preserve language hints
• Children macro: Converts to list of child pages
• Image localization: Attachment URLs → local file paths
• Hierarchical download: Child pages in subdirectories
• Retry with backoff: Handles transient API errors

Debugging

Enable HTML debug mode:

python3 scripts/download_confluence.py --save-html PAGE_ID

Creates _html_debug/ with:

• original_*.html - Raw API response
• formatted_*.html - Pretty-printed
• transformed_*.html - After macro conversion
• original_*.md - Before post-processing

See troubleshooting_guide for common issues.

Upload Guide

Complete guide for uploading Markdown content to Confluence.

Script Reference

Script: scripts/upload_confluence_v2.py

# Basic usage
python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID

# Options
--id PAGE_ID        # Page ID for updates (required if not creating)
--space SPACE_KEY   # Space key for new pages
--parent-id ID      # Parent page ID for hierarchy
--title "Title"     # Override title (defaults to H1 or frontmatter)
--dry-run           # Preview without uploading
--force-reupload    # Re-upload existing attachments
--env-file PATH     # Custom credentials file

Workflow Steps

1. Prepare Content

Ensure markdown follows these rules:

• Images use markdown syntax: ![alt](path)
• No raw Confluence XML in content
• Diagrams converted to PNG/SVG (not Mermaid/PlantUML code blocks)

2. Verify Images Exist

# List images referenced in markdown
grep -o '!\[.*\]([^)]*\.png)' document.md

# Verify files exist
ls -lh ./diagrams/

3. Test with Dry-Run

python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID --dry-run

Check output for:

• Correct mode (UPDATE/CREATE)
• All attachments found
• Content preview looks correct

4. Execute Upload

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

5. Verify Result

Open the returned URL and confirm:

• Content renders correctly
• Images display properly
• Links work

Frontmatter Support

The script reads YAML frontmatter:

---
title: Page Title
confluence:
  id: "780369923"
  space: "DEV"
parent:
  id: "123456"
---

CLI flags override frontmatter values.

Error Handling

API Details

Uses atlassian-python-api with REST API:

• No MCP size limits
• Handles attachments automatically
• Proper version management

See troubleshooting_guide for detailed error solutions.