name: confluence description: Confluence doc management. Use for Confluence URLs (/wiki/x/... short URLs), reading/uploading/downloading/searching/creating/updating pages, Markdown→ADF conversion, and syncing docs to Confluence.

Confluence Skill

Critical Rules

• DO NOT use MCP for page uploads — size limit ~10-20KB. Use upload_confluence.py instead.
• DO NOT use MCP for structural modifications — AI tool delays cause 650x slowdown (~13min vs ~1s). Use REST API scripts.
• DO NOT create temporary analysis scripts (/tmp/analyze_*.py). Use existing analyze_page.py.
• DO NOT write inline scripts to manipulate ADF JSON — use the structural scripts which handle ADF marks correctly.
• DO NOT use raw XML/HTML for images. Use markdown syntax: ![alt](path.png).
• DO NOT forget diagram conversion — pre-convert Mermaid/PlantUML to PNG/SVG before upload.
• MCP is fine for reading pages and simple text edits (Method 6).

Architecture

New page:     Markdown → markdown_to_adf.py (pre-processor + mistune) → ADF JSON → REST API v2
Edit page:    REST API v2 GET ADF → Method 6 JSON diff/patch → REST API v2 PUT ADF
Download:     REST API v2 GET ADF → adf_to_markdown.py → readable Markdown (display only)
Structural:   Direct REST API scripts (add_table_row.py, add_panel.py, etc.) → ~1s each
Attachment:   v1 REST API (no v2 equivalent)
Page width:   v1 REST API property (no v2 equivalent)
MCP fallback: markdown_to_adf() → ADF JSON → MCP createPage(contentFormat="adf")

Key points:

• Method 6 roundtrip never goes through Markdown — ADF in, ADF out
• adf_to_markdown.py is display-only (for Claude to read), not a data conversion step
• markdown_to_adf.py includes a pre-processor that fixes emoji lines (✅/❌) and [ ] checkboxes
• MCP upload: always use contentFormat: "adf", NOT "markdown" (MCP markdown merges emoji lines)
• Upload priority: REST API v2 ADF (primary) → MCP ADF (fallback, no API token)

Decision Matrix

All .py scripts run with: uv run --managed-python scripts/SCRIPT_NAME.py

Workflows

Reading Pages

1. Resolve URL → page ID:

   uv run --managed-python scripts/url_resolver.py "URL"
   

2. Read via MCP:

   mcp__plugin_confluence_atlassian__getConfluencePage({
     cloudId: "site.atlassian.net", pageId: "PAGE_ID", contentFormat: "markdown"
   })
   

Method 6: Edit Existing Pages (Recommended)

Edits text while preserving all macros. Operates directly on ADF JSON — Markdown is display-only.

When to use: Fix typos, improve clarity, update docs on pages with macros. Not for: New pages (use upload_confluence.py), massive restructuring.

Usage — natural language:

"Edit Confluence page 123456 to fix typos"
"Update API docs on page 789012"

Workflow:

1. Read page via MCP → auto-detect macros
2. Safe mode (default): edit outside macros only. Advanced mode: edit inside macros (requires confirmation)
3. Auto-backup to .confluence_backups/{page_id}/ (keeps last 10)
4. Write back via v2 API (auto-restore on failure)

Implementation: scripts/mcp_json_diff_roundtrip.py

Upload Markdown (New Page / Full Replace)

upload_confluence.py converts Markdown → ADF via markdown_to_adf.py → uploads via REST API v2.

# Update existing page
uv run --managed-python scripts/upload_confluence.py doc.md --id PAGE_ID

# Create new page
uv run --managed-python scripts/upload_confluence.py doc.md --space SPACE_KEY --parent-id PARENT_ID

# Auto-detect from frontmatter
uv run --managed-python scripts/upload_confluence.py doc.md

# Options: --dry-run, --title "...", --width narrow, --table-layout default

User intent mapping:

• "Upload X under page Y" → --space + --parent-id
• "Update page 123" → --id 123
• "Upload this downloaded file" → no args (frontmatter)

Frontmatter options:

---
title: "My Page"
confluence:
  id: "123456"
  width: full           # full (default) or narrow
  table:
    layout: full-width  # full-width (default) or default
    colwidths: [12, 10, 40, 38]
---

MCP Upload Fallback (No API Token)

Always use contentFormat: "adf" with pre-processed ADF. MCP's "markdown" mode merges emoji lines into one paragraph.

from markdown_to_adf import markdown_to_adf
import json
adf_body = markdown_to_adf(markdown_content)
# MCP createConfluencePage with contentFormat="adf", body=json.dumps(adf_body)

Download Page (Display Utility)

Downloads via v2 ADF API → converts to readable Markdown. Display only — use Method 6 for roundtrip editing.

uv run --managed-python scripts/download_confluence.py PAGE_ID
uv run --managed-python scripts/download_confluence.py --download-children PAGE_ID
uv run --managed-python scripts/download_confluence.py --output-dir ./docs PAGE_ID

Custom markers in downloaded Markdown:

• <!-- EXPAND: "title" --> ... <!-- /EXPAND -->, <!-- PANEL: type --> ... <!-- /PANEL -->
• :shortname: (emoji), <!-- MENTION: id "name" -->, <!-- CARD: url -->
• <!-- STATUS: "text" color -->, <!-- DATE: timestamp -->

These markers are recognized by upload_confluence.py for page duplication/migration.

Structural Modifications (Direct REST API)

650x faster than MCP (~1s vs ~13min). Example:

uv run --managed-python scripts/add_table_row.py PAGE_ID \
  --table-heading "Access Control Inventory" \
  --after-row-containing "GitHub" \
  --cells "Elasticsearch Cluster" "@Data Team" "Read-Only" \
  --dry-run

Common patterns for structural scripts:

# Most scripts: PAGE_ID + --after-heading or --at-end + content args + --dry-run
uv run --managed-python scripts/add_panel.py PAGE_ID --after-heading "Setup" --panel-type info --content "Note text" --dry-run
uv run --managed-python scripts/add_list_item.py PAGE_ID --after-heading "TODO" --item "New task" --position end
uv run --managed-python scripts/insert_section.py PAGE_ID --new-heading "New Section" --level 2 --after-heading "Existing"
uv run --managed-python scripts/add_media.py PAGE_ID --image-path "./img.png" --at-end --width 500
uv run --managed-python scripts/add_status.py PAGE_ID --search-text "Status:" --status "TODO" --color blue
uv run --managed-python scripts/add_mention.py PAGE_ID --search-text "Owner:" --user-id "557058..." --display-name "John"
uv run --managed-python scripts/analyze_page.py PAGE_ID [--type codeBlock|table|bulletList]

Search (MCP)

mcp__plugin_confluence_atlassian__searchConfluenceUsingCql({
  cloudId: "site.atlassian.net",
  cql: 'space = "DEV" AND text ~ "API"',
  limit: 10
})

Convert Markdown ↔ Wiki Markup

uv run --managed-python scripts/convert_markdown_to_wiki.py input.md output.wiki

Create/Update Pages via MCP (Small Documents Only)

// Create page
mcp__plugin_confluence_atlassian__createConfluencePage({
  cloudId: "site.atlassian.net", spaceId: "SPACE_ID",
  title: "Page Title", contentFormat: "adf", body: JSON.stringify(adfJson)
})

// Update page
mcp__plugin_confluence_atlassian__updateConfluencePage({
  cloudId: "site.atlassian.net", pageId: "PAGE_ID",
  title: "Title", contentFormat: "adf", body: JSON.stringify(adfJson)
})

Editing Existing Pages: Decision Order

1. Structural scripts (add_table_row, insert_section, add_panel...) → precise, fast, ~1s
2. Method 6 (mcp_json_diff_roundtrip) → free-form text editing, fix typos, AI-driven
3. upload_confluence.py → full page replacement (last resort)

Always start with analyze_page.py PAGE_ID to understand the page structure first.

Common Mistakes

Image Handling

1. Convert diagrams if needed: mmdc -i diagram.mmd -o diagram.png or plantuml diagram.puml -tpng
2. Use markdown syntax: ![alt](./path/to/image.png)
3. Upload: uv run --managed-python scripts/upload_confluence.py doc.md --id PAGE_ID

Checklists

Upload: Convert diagrams → Use markdown image syntax → --dry-run test → Upload with script → Verify page

Download: Get page ID (use url_resolver.py for short URLs) → Set output dir → Run download → Verify attachments

Script Reference

All scripts: uv run --managed-python scripts/SCRIPT_NAME.py

All structural scripts support --dry-run for preview.

Scripts that accept text input (add_list_item, add_panel, add_blockquote, insert_section, add_nested_expand) support markdown inline syntax which is auto-converted to ADF marks:

• `code` → code mark, **bold** → strong mark, *italic* → em mark, ~~strike~~ → strike mark

Example: --item '"compat"- **REQUIRED** for all models' correctly renders as code + bold in Confluence.

When NOT to Use Scripts

• Simple page reads → MCP directly
• Small content, no images (<10KB) → MCP may work
• Jira issues → Use Jira-specific tools

Prerequisites

• uv — all scripts use PEP 723 inline metadata
• Env vars: CONFLUENCE_URL, CONFLUENCE_USER, CONFLUENCE_API_TOKEN (for REST API scripts)
• MCP: Atlassian MCP Server with Confluence credentials (for reading/Method 6)
• Optional: mark CLI (Git-to-Confluence sync), Mermaid CLI (diagram rendering)

References

• Wiki Markup Guide - Syntax reference
• CQL Reference - Query language
• Mention Account ID Lookup - Find user IDs
• Troubleshooting - Common errors and fixes