Confluence

Confluence Management Skill

Manage Confluence documentation through Claude Code: download pages to Markdown, upload large documents with images, convert between formats, and integrate Mermaid/PlantUML diagrams.

Table of Contents

• Quick Decision Matrix
• MCP Size Limits
• Prerequisites
• Core Workflows
• Reference Documentation

Quick Decision Matrix

MCP Size Limits

MCP tools have size limits (10-20KB) for uploads. For large documents or pages with images, use the REST API via upload_confluence_v2.py:

# Upload large document
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id 780369923

# Dry-run preview
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id 780369923 --dry-run

MCP works for reading pages but not for uploading large content.

Prerequisites

Required

• Atlassian MCP Server (mcp__atlassian-evinova) 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)

Core Workflows

Download Pages to Markdown

# Single page
python3 ~/.claude/skills/confluence/scripts/download_confluence.py 123456789

# With child pages
python3 ~/.claude/skills/confluence/scripts/download_confluence.py --download-children 123456789

# Custom output directory
python3 ~/.claude/skills/confluence/scripts/download_confluence.py --output-dir ./docs 123456789

See Downloading Guide for details.

Upload Pages with Images

1. Convert diagrams to images first using design-doc-mermaid or plantuml skills 2. Reference images with standard markdown: ![Description](./images/diagram.png) 3. Upload via REST API:

python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md --id PAGE_ID

See Image Handling Best Practices for details.

Search Confluence

mcp__atlassian-evinova__confluence_search({
  query: 'space = "DEV" AND text ~ "API"',
  limit: 10
})

Create/Update Pages (Small Documents)

// Create page
mcp__atlassian-evinova__confluence_create_page({
  space_key: "DEV",
  title: "API Documentation",
  content: "h1. Overview\n\nContent here...",
  content_format: "wiki"
})

// Update page
mcp__atlassian-evinova__confluence_update_page({
  page_id: "123456789",
  title: "Updated Title",
  content: "h1. New Content",
  version_comment: "Updated via Claude Code"
})

Sync from Git (mark CLI)

Add metadata to Markdown files:

<!-- Space: DEV -->
<!-- Parent: Documentation -->
<!-- Title: API Guide -->

# API Guide
Content...

Sync to Confluence:

mark -f documentation.md
mark --dry-run -f documentation.md  # Preview first

See mark Tool Guide for details.

Convert Between Formats

See Conversion Guide for the complete conversion matrix.

Quick reference:

Reference Documentation

Detailed guides in the references/ directory:

Available MCP Tools

Utility Scripts

---

Version: 2.1.0 | Last Updated: 2025-01-21

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-evinova__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: Evinova Agent Documentation 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

Confluence Skill for Claude Code

  

A comprehensive Claude Code skill that provides expert guidance for managing Confluence documentation, including Wiki Markup mastery, Markdown conversion, Mermaid diagram integration, and seamless interaction with the Atlassian MCP server.

---

Table of Contents

• What is a Skill?
• How This Skill Works
• Installing with Skilz (Universal Installer)
• Installation Levels
• Multi-Instance Confluence Support
• Prerequisites
• Quick Start
• Uploading Markdown to Confluence
• Features
• File Structure
• Key Documentation
• Common Workflows
• Best Practices
• Troubleshooting
• Integration with Other Skills
• Advanced Usage
• CI/CD Integration
• Updates and Maintenance
• Support
• Contributing
• License
• Related Resources

---

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-evinova). The MCP provides raw access to Confluence's API capabilities, while this skill provides:

• Format conversion expertise for Markdown to 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.

---

Installing with Skilz (Universal Installer)

The recommended way to install this skill across different AI coding agents is using the skilz universal installer.

Install Skilz

pip install skilz

This skill supports Agent Skill Standard which means it supports 14 plus coding agents including Claude Code, OpenAI Codex, Cursor and Gemini.

Git URL Options

You can use either -g or --git with HTTPS or SSH URLs:

# HTTPS URL
skilz install -g https://github.com/SpillwaveSolutions/confluence-skill

# SSH URL
skilz install --git git@github.com:SpillwaveSolutions/confluence-skill.git

Claude Code

Install to user home (available in all projects):

skilz install -g https://github.com/SpillwaveSolutions/confluence-skill

Install to current project only:

skilz install -g https://github.com/SpillwaveSolutions/confluence-skill --project

OpenCode

Install for OpenCode:

skilz install -g https://github.com/SpillwaveSolutions/confluence-skill --agent opencode

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/confluence-skill --project --agent opencode

Gemini

Project-level install for Gemini:

skilz install -g https://github.com/SpillwaveSolutions/confluence-skill --agent gemini

OpenAI Codex

Install for OpenAI Codex:

skilz install -g https://github.com/SpillwaveSolutions/confluence-skill --agent codex

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/confluence-skill --project --agent codex

Install from Skillzwave Marketplace

# Claude to user home dir ~/.claude/skills
skilz install SpillwaveSolutions_confluence-skill/confluence

# Claude skill in project folder ./claude/skills
skilz install SpillwaveSolutions_confluence-skill/confluence --project

# OpenCode install to user home dir ~/.config/opencode/skills
skilz install SpillwaveSolutions_confluence-skill/confluence --agent opencode

# OpenCode project level
skilz install SpillwaveSolutions_confluence-skill/confluence --agent opencode --project

# OpenAI Codex install to user home dir ~/.codex/skills
skilz install SpillwaveSolutions_confluence-skill/confluence

# OpenAI Codex project level ./.codex/skills
skilz install SpillwaveSolutions_confluence-skill/confluence --agent opencode --project


# Gemini CLI (project level) -- only works with project level
skilz install SpillwaveSolutions_confluence-skill/confluence --agent gemini

See this site skill Listing to see how to install this exact skill to 14+ different coding agents.

Other Supported Agents

Skilz supports 14+ coding agents including Claude Code, OpenAI Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Windsurf, Qwen Code, Aidr, and more.

For the full list of supported platforms, visit SkillzWave.ai/platforms or see the skilz-cli GitHub repository

<a href="https://skillzwave.ai/">Largest Agentic Marketplace for AI Agent Skills</a> and <a href="https://spillwave.com/">SpillWave: Leaders in AI Agent Development.</a>

---

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-evinova": {
      "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-evinova": {
      "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

Using skilz (recommended):

pip install skilz
skilz install -g https://github.com/SpillwaveSolutions/confluence-skill

Or manually:

# Global installation
mkdir -p ~/.claude/skills/
cd ~/.claude/skills/
git clone https://github.com/SpillwaveSolutions/confluence-skill confluence

# OR workspace installation
mkdir -p ~/workspace/acme-corp/.claude/skills/
cd ~/workspace/acme-corp/.claude/skills/
git clone https://github.com/SpillwaveSolutions/confluence-skill confluence

# OR project installation
mkdir -p /path/to/project/.claude/skills/
cd /path/to/project/.claude/skills/
git clone https://github.com/SpillwaveSolutions/confluence-skill confluence

2. Configure Atlassian MCP

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

{
  "mcpServers": {
    "atlassian-evinova": {
      "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:

````markdown

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 to update existing page
• Reads confluence.version to auto-increment to version 3
• Reads confluence.space to use for creation if no ID
• Reads parent.id to set parent page relationship

Script 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 to Confluence Wiki Markup
• Wiki Markup to 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 to 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 to 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
• SkillzWave Marketplace
• Agent Skill Standard
• skilz CLI

Confluence Storage Format Reference

Understanding how Confluence stores and renders page content.

Table of Contents

• What is Storage Format
• Common Storage Format Elements
• Confluence Macros
• Converting Markdown to Storage Format
• HTML Escaping Issues
• REST API Upload
• Common Pitfalls

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 to Wiki Markup Conversion Guide

Detailed conversion rules and examples for converting between Markdown and Confluence Wiki Markup.

Table of Contents

• Conversion Matrix
• Links
• Images
• Tables
• Code Blocks
• Blockquotes
• Special Elements
• Limitations

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

Image Handling Best Practices for Confluence

Guidelines for correctly handling images when uploading to Confluence.

Table of Contents

• MCP Size Limits
• Image Type Support
• Workflow for Each Image Type
• Common Mistakes
• Recommended Workflow
• File Size Guidelines

MCP Size Limits

MCP has size limits and cannot upload large documents with images. Use the REST API directly via the upload scripts.

Image Type Support

The confluence skill supports multiple image types:

1. Regular Images - PNG, JPG, GIF, SVG files 2. Mermaid Diagrams - Convert to PNG/SVG first using design-doc-mermaid skill 3. PlantUML Diagrams - Convert to PNG/SVG using plantuml skill 4. External Images - Referenced via URL (not uploaded as attachments)

Workflow for Each Image Type

Regular Images (PNG, JPG, SVG, etc.)

Use Case: Screenshots, logos, photos, hand-drawn diagrams

Workflow: 1. Place image files in a directory (e.g., ./images/) 2. Reference in markdown using standard syntax:

   ![Logo](./images/logo.png)
   ![Screenshot](./images/screenshot.jpg)

3. Upload using upload_confluence_v2.py:

   python3 upload_confluence_v2.py document.md --id 780369923

What Happens:

• md2cf detects image paths and converts to: <ac:image><ri:attachment ri:filename="logo.png"/></ac:image>
• Image paths added to renderer.attachments list
• Upload script uploads images as page attachments
• Images render inline in Confluence

Mermaid Diagrams

Use Case: Architecture diagrams, flowcharts, sequence diagrams, state machines

Option 1: Use design-doc-mermaid Skill (Recommended)

The design-doc-mermaid skill provides comprehensive Mermaid diagram support.

Workflow: 1. Invoke skill: Skill: "design-doc-mermaid" 2. Follow skill prompts to convert Mermaid code to images 3. Reference generated images in markdown:

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

4. Upload to Confluence using this skill's upload script

Option 2: Manual Conversion

# Install mermaid-cli if needed
npm install -g @mermaid-js/mermaid-cli

# Convert Mermaid to PNG
mmdc -i architecture.mmd -o architecture.png -b transparent

# Convert Mermaid to SVG
mmdc -i architecture.mmd -o architecture.svg -b transparent

Reference in Markdown:

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

*Figure 1: System Architecture*

Do NOT:

• ❌ Use Mermaid code blocks in markdown when uploading to Confluence
• ❌ Use MermaidConfluenceRenderer directly (it breaks regular images)
• ❌ Put raw <ac:image> XML in markdown (gets escaped as literal text)

PlantUML Diagrams

Use Case: UML diagrams, component diagrams, deployment diagrams, ER diagrams

Use plantuml Skill (Recommended)

The plantuml skill provides complete PlantUML diagram support.

Workflow: 1. Invoke skill: Skill: "plantuml" 2. Follow skill prompts to convert PlantUML code to images 3. Reference generated images in markdown:

   ![Deployment Diagram](./diagrams/deployment.png)

4. Upload to Confluence using this skill's upload script

Manual Conversion (Alternative):

# Install PlantUML if needed
# See plantuml skill documentation

# Convert PlantUML to PNG
plantuml diagram.puml -tpng

# Convert PlantUML to SVG
plantuml diagram.puml -tsvg

Reference in Markdown:

![Component Diagram](./diagrams/components.png)

*Figure 2: Component Architecture*

External Images (URLs)

Use Case: Images hosted elsewhere, CDN images, remote resources

Workflow: 1. Reference external URL directly in markdown:

   ![Remote Image](https://example.com/logo.png)

Note: External images are NOT uploaded as attachments. Confluence embeds them via URL reference.

The md2cf Conversion Process

How ConfluenceRenderer Handles Images

Input (Markdown):

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

Processing: 1. ConfluenceRenderer detects markdown image syntax 2. Extracts alt text: "Architecture Diagram" 3. Extracts path: "./diagrams/architecture.png" 4. Adds path to renderer.attachments list (as string) 5. Generates storage format XML

Output (Storage Format):

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

Attachments List:

renderer.attachments = ['./diagrams/architecture.png']

Image Syntax Support

Standard Markdown (Supported):

![Alt Text](./path/to/image.png)
![](./image.png)  # Alt text optional
![Diagram](../images/diagram.svg)  # Relative paths OK

With Width/Height (NOT Supported by Standard Markdown):

To control image size in Confluence, you need to: 1. Upload image first 2. Manually adjust size in Confluence UI 3. Or use Confluence wiki markup in source (advanced)

Common Mistakes and Fixes

❌ Mistake 1: Using Raw Confluence XML

Wrong:

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

What Happens: Text appears literally as escaped HTML:

<ac:image>...</ac:image>

Fix: Use markdown image syntax:

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

❌ Mistake 2: Using Mermaid Code Blocks

Wrong:

# Architecture

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

What Happens:

• If using base ConfluenceRenderer: Appears as code block, not diagram
• If using MermaidConfluenceRenderer: Breaks regular image handling

Fix: Convert Mermaid to PNG first:

# Use design-doc-mermaid skill OR manually:
mmdc -i arch.mmd -o arch.png

# Then reference in markdown:
![Architecture](./arch.png)

❌ Mistake 3: Using MermaidConfluenceRenderer with Regular Images

Wrong (in upload script):

from mermaid_renderer import MermaidConfluenceRenderer

renderer = MermaidConfluenceRenderer()  # ❌ Breaks regular images!

What Happens: MermaidConfluenceRenderer overwrites parent's attachments attribute, breaking regular markdown image detection.

Fix: Use base ConfluenceRenderer:

from md2cf.confluence_renderer import ConfluenceRenderer

renderer = ConfluenceRenderer()  # ✅ Works with all images

Then convert diagrams to images separately using appropriate skill.

❌ Mistake 4: Forgetting to Upload Attachments

Wrong:

# Only upload page content
confluence.update_page(
    page_id=page_id,
    body=storage_html,
    representation='storage'
)
# Missing: attachment upload!

What Happens: Confluence shows placeholder icons or broken image links.

Fix: Upload attachments after page content:

# Upload page
confluence.update_page(...)

# Upload attachments
for image_path in attachments:
    confluence.attach_file(
        filename=image_path,
        page_id=page_id,
        ...
    )

Recommended Workflow (Complete Example)

Goal: Upload technical document with Mermaid diagrams and screenshots to Confluence.

Step 1: Prepare Images

# Convert Mermaid diagrams to PNG using design-doc-mermaid skill
# (or manually with mmdc)

# Place screenshots in images directory
mkdir -p ./images
cp ~/screenshots/*.png ./images/

# Organize generated diagrams
mkdir -p ./diagrams
mv *.png ./diagrams/

Step 2: Write Markdown with Image References

# Technical Architecture Document

## Overview

This document describes our system architecture.

## Architecture Diagram

![High-Level Architecture](./diagrams/architecture.png)

*Figure 1: High-Level System Architecture (C4 Container Style)*

## User Interface

Here's a screenshot of the main dashboard:

![Dashboard Screenshot](./images/dashboard.png)

*Figure 2: Main Dashboard Interface*

## Deployment Diagram

![Deployment Architecture](./diagrams/deployment.png)

*Figure 3: Deployment Architecture on AWS*

Step 3: Upload to Confluence

# Use upload_confluence_v2.py script
python3 ~/.claude/skills/confluence/scripts/upload_confluence_v2.py \
    document.md \
    --id 780369923 \
    --env-file /path/to/.env.jira

What Happens: 1. Script reads markdown file 2. md2cf converts markdown to storage format 3. md2cf detects 3 images and adds to attachments list 4. Script uploads page content via REST API 5. Script uploads 3 image files as attachments 6. Confluence renders images inline in page

Result: ✅ Complete document with all images rendering correctly!

Skill Integration

Using design-doc-mermaid Skill

When to Use:

• Creating architecture diagrams from Mermaid code
• Generating multiple diagram types (sequence, class, state, etc.)
• Need comprehensive Mermaid diagram support

Workflow:

1. Invoke skill: Skill: "design-doc-mermaid"
2. Provide Mermaid diagram code when prompted
3. Skill generates PNG/SVG images
4. Reference generated images in your markdown
5. Upload to Confluence using this confluence skill

See: ~/.claude/skills/design-doc-mermaid/SKILL.md for complete documentation.

Using plantuml Skill

When to Use:

• Creating UML diagrams (class, component, deployment, etc.)
• ER diagrams, activity diagrams
• Complex diagram types not supported by Mermaid

Workflow:

1. Invoke skill: Skill: "plantuml"
2. Provide PlantUML diagram code when prompted
3. Skill generates PNG/SVG images
4. Reference generated images in your markdown
5. Upload to Confluence using this confluence skill

See: ~/.claude/skills/plantuml/SKILL.md for complete documentation.

Size Limits and Performance

MCP Size Limits (CRITICAL)

DO NOT USE MCP FOR CONFLUENCE PAGE UPLOADS.

• ❌ mcp__atlassian-evinova__confluence_update_page - Has size limits
• ❌ mcp__atlassian-evinova__confluence_create_page - Has size limits

Use REST API Instead:

• ✅ upload_confluence_v2.py - No size limits, handles large documents

Image File Size Recommendations

• PNG Screenshots: Keep under 500KB (optimize with tools like pngquant)
• PNG Diagrams: Usually small (< 100KB)
• SVG Diagrams: Very small (< 50KB), preferred for diagrams
• JPG Photos: Keep under 1MB, use 80-85% quality

Page Size Guidelines

• Small Pages: < 50KB - No issues
• Medium Pages: 50KB - 500KB - Use REST API, avoid MCP
• Large Pages: > 500KB - Use REST API, test thoroughly
• Very Large: > 1MB - Consider splitting into multiple pages

Troubleshooting

Problem: Images appear as literal <ac:image> text

Solution: You put raw XML in markdown. Use ![](path.png) syntax instead.

---

Problem: Images show as broken icons/placeholders

Solution: Attachments weren't uploaded. Verify attach_file() calls completed.

---

Problem: "String indices must be integers" error

Solution: API response structure issue. Use upload_confluence_v2.py which handles this correctly.

---

Problem: MCP size limit error

Solution: Don't use MCP. Use upload_confluence_v2.py script instead.

---

Problem: Regular images stopped working after adding Mermaid support

Solution: Don't use MermaidConfluenceRenderer. Use base ConfluenceRenderer and convert diagrams separately.

References

• confluence_storage_format.md - Storage format details
• troubleshooting_guide.md - Common errors and fixes
• ~/.claude/skills/design-doc-mermaid/SKILL.md - Mermaid diagram skill
• ~/.claude/skills/plantuml/SKILL.md - PlantUML diagram skill

Complete Guide to the mark Tool

mark - A command-line tool for syncing Markdown documentation to Atlassian Confluence

>

GitHub: https://github.com/kovetskiy/mark

Purpose: Documentation-as-Code workflow for Confluence

Table of Contents

• Overview
• Installation
• Configuration
• Markdown Metadata
• Basic Usage
• Advanced Features
• File Uploads and Attachments
• CI/CD Integration
• Best Practices
• Troubleshooting

Overview

What is mark?

mark is a CLI tool that:

• Converts Markdown files to Confluence pages
• Synchronizes content between Git repositories and Confluence
• Manages page hierarchies and relationships
• Uploads attachments referenced in Markdown
• Creates pages and parent pages automatically
• Updates existing pages with new content
• Applies labels for organization

Key Benefits

1. Documentation-as-Code: Keep docs in Git with your code 2. Automation-Friendly: Perfect for CI/CD pipelines 3. Single Source of Truth: Markdown in Git, auto-sync to Confluence 4. Version Control: Track documentation changes alongside code 5. Collaboration: Team can review docs via pull requests 6. Consistency: Maintain formatting standards via templates

How It Works

graph LR
    A[Markdown File] --> B[mark CLI]
    B --> C{Parse Metadata}
    C --> D[Convert to HTML]
    D --> E[Confluence REST API]
    E --> F{Page Exists?}
    F -->|No| G[Create Page]
    F -->|Yes| H[Update Page]
    G --> I[Upload Attachments]
    H --> I
    I --> J[Apply Labels]

Installation

macOS (Homebrew)

brew install kovetskiy/mark/mark

Linux/macOS (Go)

go install github.com/kovetskiy/mark@latest

Docker

docker pull kovetskiy/mark

# Run with Docker
docker run --rm -v $(pwd):/docs kovetskiy/mark -f /docs/README.md

From Source

git clone https://github.com/kovetskiy/mark.git
cd mark
go build -o mark
sudo mv mark /usr/local/bin/

Direct Download

# Download latest release
curl -LO https://github.com/kovetskiy/mark/releases/latest/download/mark

# Make executable
chmod +x mark

# Move to PATH
sudo mv mark /usr/local/bin/

Verify Installation

mark --version

Configuration

Configuration File

Create ~/.config/mark (or ~/.config/mark.toml):

# Confluence credentials
username = "your-email@example.com"
password = "your-api-token-here"

# Confluence instance URL (include /wiki for Cloud)
base_url = "https://your-instance.atlassian.net/wiki"

# Optional: Default space
space = "DEV"

# Optional: Enable debug logging
debug = false

# Optional: Dry run mode (preview without making changes)
dry_run = false

Environment Variables

Alternatively, use environment variables:

export CONFLUENCE_USERNAME="your-email@example.com"
export CONFLUENCE_PASSWORD="your-api-token-here"
export CONFLUENCE_BASE_URL="https://your-instance.atlassian.net/wiki"

API Token Generation

For Confluence Cloud:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens 2. Click "Create API token" 3. Give it a name (e.g., "mark CLI") 4. Copy the token (save it securely!) 5. Use your email as username, token as password

For Confluence Server/Data Center:

Use your username and password, or configure SSO/OAuth if required.

Markdown Metadata

Required Metadata

Every Markdown file synced with mark must include metadata in HTML comments:

<!-- Space: DEV -->
<!-- Title: My Page Title -->

# My Page Title

Content goes here...

Metadata Fields

Space (Required)

<!-- Space: DEV -->

The Confluence space key where the page will be created.

Title (Optional)

<!-- Title: API Documentation -->

Page title. If omitted, mark will infer from the first H1 heading.

Parent (Optional, Multiple Allowed)

<!-- Parent: API Guides -->

Create page hierarchy. Multiple Parent lines create nested structure:

<!-- Space: DEV -->
<!-- Parent: Documentation -->
<!-- Parent: API Guides -->
<!-- Parent: REST API -->
<!-- Title: Authentication -->

This creates:

Documentation/
  └── API Guides/
      └── REST API/
          └── Authentication

Important: Parents are specified from outermost to innermost.

Label (Optional, Multiple Allowed)

<!-- Label: api -->
<!-- Label: documentation -->
<!-- Label: authentication -->

Add labels to the page for organization and searchability.

Attachment (Optional, Multiple Allowed)

<!-- Attachment: diagrams/architecture.png -->
<!-- Attachment: files/api-spec.yaml -->

Upload local files as attachments. Paths are relative to the Markdown file location.

Complete Example

<!-- Space: DEV -->
<!-- Parent: Documentation -->
<!-- Parent: API Guides -->
<!-- Title: REST API Authentication Guide -->
<!-- Label: api -->
<!-- Label: authentication -->
<!-- Label: security -->
<!-- Attachment: diagrams/auth-flow.png -->
<!-- Attachment: examples/auth-example.json -->

# REST API Authentication Guide

This guide explains how to authenticate with our REST API.

## Overview

We use OAuth 2.0 for authentication...

## Architecture

![Authentication Flow](diagrams/auth-flow.png)

## Example

See the example request in [auth-example.json](examples/auth-example.json).

Basic Usage

Sync a Single File

mark -f documentation.md

Specify Credentials

mark -u user@example.com -p api-token -f documentation.md

Use Custom Config File

mark -c ~/.config/mark-production -f documentation.md

Dry Run (Preview)

mark --dry-run -f documentation.md

This shows what would happen without making actual changes.

Verbose Output

mark -v -f documentation.md

Debug Mode

mark --debug -f documentation.md

Advanced Features

Automatic Page Creation

If the target page doesn't exist, mark will: 1. Create the page 2. Create parent pages if they don't exist 3. Set up the correct hierarchy

Automatic Updates

If the page already exists, mark will: 1. Update the content 2. Increment the version number 3. Preserve page history 4. Maintain page ID and URL

Version Comments

Pass a commit message or version comment:

mark -f documentation.md --version-message "Updated API endpoints"

In CI/CD:

mark -f documentation.md --version-message "$CI_COMMIT_MESSAGE"

Multiple Files

Sync multiple files in a directory:

for file in docs/**/*.md; do
  mark -f "$file"
done

Or use a script:

#!/bin/bash
find docs/ -name "*.md" -type f | while read file; do
  echo "Syncing $file..."
  mark -f "$file"
done

File Uploads and Attachments

How Attachments Work

1. Reference files in the Attachment metadata 2. mark uploads them to Confluence 3. Files become page attachments 4. Reference attachments in Markdown

Attachment Metadata

<!-- Attachment: path/to/file.pdf -->
<!-- Attachment: images/diagram.png -->
<!-- Attachment: data/sample.csv -->

Important: Paths are relative to the Markdown file location.

Referencing Attachments in Content

Images:

![Diagram](images/diagram.png)

Links:

Download the [API specification](files/api-spec.yaml).

Supported File Types

Mark supports all file types that Confluence accepts:

• Images: PNG, JPG, GIF, SVG
• Documents: PDF, DOCX, XLSX, PPTX
• Code: JSON, YAML, XML, TXT
• Archives: ZIP, TAR.GZ
• And more...

Attachment Updates

When you re-run mark:

• Existing attachments are updated if the file changed
• New attachments are uploaded
• Removed attachments remain on the page (mark doesn't delete)

Example with Multiple Attachments

<!-- Space: PROJ -->
<!-- Title: Project Documentation -->
<!-- Attachment: diagrams/architecture.png -->
<!-- Attachment: diagrams/workflow.png -->
<!-- Attachment: specs/requirements.pdf -->
<!-- Attachment: data/metrics.csv -->

# Project Documentation

## Architecture

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

## Workflow

![Development Workflow](diagrams/workflow.png)

## Requirements

See [requirements.pdf](specs/requirements.pdf) for detailed specifications.

## Metrics

Latest metrics are available in [metrics.csv](data/metrics.csv).

CI/CD Integration

GitHub Actions

name: Sync Documentation to Confluence

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

jobs:
  sync-confluence:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        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: 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
            echo "Syncing $file..."
            mark -u "$CONFLUENCE_USERNAME" \
                 -p "$CONFLUENCE_PASSWORD" \
                 --base-url "$CONFLUENCE_BASE_URL" \
                 -f "$file" \
                 --version-message "Updated from commit ${{ github.sha }}"
          done

      - name: Summary
        run: echo "✅ Documentation synced to Confluence"

GitLab CI

sync-to-confluence:
  stage: deploy
  only:
    - main
  changes:
    - docs/**/*.md
  script:
    - curl -LO https://github.com/kovetskiy/mark/releases/latest/download/mark
    - chmod +x mark
    - mv mark /usr/local/bin/
    - |
      for file in docs/**/*.md; do
        echo "Syncing $file..."
        mark -u "$CONFLUENCE_USERNAME" \
             -p "$CONFLUENCE_PASSWORD" \
             --base-url "$CONFLUENCE_BASE_URL" \
             -f "$file" \
             --version-message "$CI_COMMIT_MESSAGE"
      done
  variables:
    CONFLUENCE_USERNAME: ${CONFLUENCE_USERNAME}
    CONFLUENCE_PASSWORD: ${CONFLUENCE_API_TOKEN}
    CONFLUENCE_BASE_URL: ${CONFLUENCE_BASE_URL}

Jenkins Pipeline

pipeline {
    agent any

    stages {
        stage('Sync to Confluence') {
            when {
                changeset "docs/**/*.md"
                branch 'main'
            }
            steps {
                sh '''
                    curl -LO https://github.com/kovetskiy/mark/releases/latest/download/mark
                    chmod +x mark
                    sudo mv mark /usr/local/bin/

                    for file in docs/**/*.md; do
                        echo "Syncing $file..."
                        mark -u "${CONFLUENCE_USERNAME}" \
                             -p "${CONFLUENCE_PASSWORD}" \
                             --base-url "${CONFLUENCE_BASE_URL}" \
                             -f "$file" \
                             --version-message "${GIT_COMMIT_MSG}"
                    done
                '''
            }
        }
    }
}

Best Practices

1. Directory Structure

Organize documentation in a clear structure:

docs/
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
├── guides/
│   ├── getting-started.md
│   └── advanced.md
├── diagrams/
│   ├── architecture.png
│   └── workflow.png
└── templates/
    └── page-template.md

2. Consistent Metadata

Create a template for consistent metadata:

<!-- Space: DEV -->
<!-- Parent: Documentation -->
<!-- Parent: [Section Name] -->
<!-- Title: [Page Title] -->
<!-- Label: documentation -->
<!-- Label: [additional-labels] -->

# [Page Title]

[Content here...]

3. Version Control

• Commit documentation alongside code changes
• Use meaningful commit messages (they become version comments)
• Review docs in pull requests
• Tag releases to sync documentation versions

4. Automation Strategy

• On PR merge: Sync to Confluence automatically
• Daily sync: Catch any manual updates
• Release sync: Update version-specific documentation
• Dry run on PRs: Validate before merging

5. Page Hierarchy Planning

Plan your Confluence structure before adding metadata:

Space: DEV
└── Documentation (parent page, created manually or by mark)
    ├── Getting Started
    │   ├── Installation
    │   └── Quick Start
    ├── API Guides
    │   ├── Authentication
    │   ├── Endpoints
    │   └── Error Handling
    └── Architecture
        ├── Overview
        └── Diagrams

6. Attachment Management

• Keep attachments in subdirectories (e.g., diagrams/, files/)
• Use descriptive filenames
• Optimize image sizes before committing
• Use SVG for diagrams when possible
• Version control all attachments

7. Label Strategy

Use consistent labeling:

<!-- Label: documentation -->  # All docs
<!-- Label: api -->            # API-related
<!-- Label: guide -->          # User guides
<!-- Label: v2.0 -->           # Version tags
<!-- Label: draft -->          # Work in progress

8. Testing

Before mass deployment:

1. Test with --dry-run first 2. Sync a single test file 3. Verify in Confluence 4. Then automate for all files

9. Monitoring

• Log mark output in CI/CD
• Alert on failures
• Track sync success/failure metrics
• Periodically audit Confluence vs Git

Troubleshooting

Issue: Authentication Failed

Symptoms:

Error: 401 Unauthorized

Solutions: 1. Verify API token is valid 2. Check username is your email (for Cloud) 3. Ensure base_url includes /wiki for Cloud 4. Regenerate API token if needed

Test credentials:

curl -u "email@example.com:API_TOKEN" \
  https://your-instance.atlassian.net/wiki/rest/api/space

Issue: Page Not Found

Symptoms:

Error: Parent page not found

Solutions: 1. Verify space key is correct (case-sensitive) 2. Check parent page exists 3. Ensure parent page title matches exactly 4. Create parent pages manually first

Issue: Attachments Not Uploading

Symptoms: Attachments missing from Confluence page

Solutions: 1. Verify file paths are relative to Markdown file 2. Check files exist at specified paths 3. Ensure file sizes are within Confluence limits 4. Check file permissions (readable by mark)

Debug:

mark --debug -f documentation.md 2>&1 | grep -i attachment

Issue: Markdown Not Converting Properly

Symptoms: Formatting looks wrong in Confluence

Solutions: 1. Check Markdown syntax is standard 2. Avoid custom extensions not supported by mark 3. Test conversion with smaller sections 4. Review mark's supported Markdown features

Issue: Slow Syncing

Symptoms: mark takes a long time to sync

Solutions: 1. Optimize image sizes (compress before uploading) 2. Reduce number of attachments per page 3. Use --dry-run to test without uploading 4. Batch sync files in parallel (carefully)

Issue: Duplicate Pages Created

Symptoms: Multiple pages with same title

Solutions: 1. Ensure Title metadata is consistent 2. Check for special characters in titles 3. Verify space key is correct 4. Delete duplicates manually in Confluence

Command Reference

Common Commands

# Basic sync
mark -f file.md

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

# Custom base URL
mark --base-url https://instance.atlassian.net/wiki -f file.md

# Dry run (preview)
mark --dry-run -f file.md

# Verbose output
mark -v -f file.md

# Debug mode
mark --debug -f file.md

# Custom config
mark -c ~/.config/mark-prod -f file.md

# With version comment
mark -f file.md --version-message "Updated content"

# Help
mark --help

Configuration Options

# ~/.config/mark

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

Limitations and Considerations

What mark Does NOT Do

1. Does not delete pages: Removing a Markdown file won't delete the Confluence page 2. No bidirectional sync: Changes in Confluence won't sync back to Markdown 3. Limited macro support: Complex Confluence macros may not be supported 4. No attachment deletion: Old attachments remain when removed from metadata

Supported Markdown Features

✅ Supported:

• Headings (H1-H6)
• Bold, italic, strikethrough
• Lists (ordered, unordered, nested)
• Code blocks with syntax highlighting
• Tables
• Links
• Images
• Blockquotes
• Horizontal rules

❌ Not Supported:

• Some GitHub-flavored Markdown extensions
• Footnotes
• Definition lists
• Task lists (may render incorrectly)
• Some advanced table features

Additional Resources

• GitHub Repository: https://github.com/kovetskiy/mark
• Issue Tracker: https://github.com/kovetskiy/mark/issues
• Releases: https://github.com/kovetskiy/mark/releases
• Confluence REST API: https://developer.atlassian.com/cloud/confluence/rest/

Integration with Claude Code Confluence Skill

This guide is part of the Claude Code Confluence skill. Use mark in combination with:

1. Claude Code MCP tools: For interactive page management 2. Conversion scripts: To prepare Markdown for mark 3. Mermaid rendering: To generate diagrams before syncing 4. Metadata generation: To automatically add mark metadata

Workflow Example

# 1. Add metadata using skill script
python scripts/generate_mark_metadata.py README.md \
  --space DEV \
  --parent "Documentation" \
  --labels documentation,api

# 2. Render Mermaid diagrams
python scripts/render_mermaid.py --extract-from-markdown README.md

# 3. Sync to Confluence with mark
mark -f README.md

# 4. Verify using MCP tools (via Claude Code)
# "Search for the page we just created and show me the result"

---

Version: 1.0.0 Last Updated: 2025-01-21 Part of: Claude Code Confluence Skill