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
• REST Script Workflows
• Prerequisites
• Core Workflows
• Reference Documentation

##Quick Decision Matrix

##REST Script Workflows

Use the REST API scripts for Confluence reads and writes. Always run --dry-run before writes:

# Upload large document
python3 scripts/upload_confluence_v2.py \
    document.md --id 780369923

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

Local Server/Data Center auth supports CONFLUENCE_PERSONAL_TOKEN, CONFLUENCE_AUTH_TYPE=bearer, and optional CONFLUENCE_CONTEXT_PATH. Do not print token values.

##Prerequisites

###Required

• Confluence credentials exported in the environment: CONFLUENCE_URL, CONFLUENCE_USERNAME, and CONFLUENCE_PERSONAL_TOKEN or CONFLUENCE_API_TOKEN

###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 scripts/download_confluence.py 123456789

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

# Custom output directory
python3 scripts/download_confluence.py --output-dir ./docs 123456789

See Downloading Guide for details.

###Upload Pages with Images and Native Diagrams

Do not replace native Confluence diagrams with image fallbacks unless explicitly requested. Markdown code fences do not become Confluence diagram macros by themselves.

For network/component diagrams, use the native draw.io macro pattern when the target Confluence instance supports it. A working storage example uses ac:structured-macro ac:name="drawio" with a diagramName parameter and a matching draw.io attachment (application/vnd.jgraph.mxfile). The PNG preview attachment belongs to the draw.io macro and is not a replacement ac:image workflow.

Native PlantUML component/class/state diagrams require server-side Graphviz dot. If Confluence renders Dot executable does not exist, Cannot find Graphviz, or suggests @startuml\ntestdot\n@enduml, the correct fix is Confluence/PlantUML plugin configuration or using the verified native draw.io macro pattern for component diagrams; do not silently replace the diagram with ac:image.

1. For ordinary document images, reference images with standard markdown: ![Description](./images/image.png).
2. For native diagrams, preserve or create the correct Confluence storage macro (drawio, plantuml, etc.) rather than raw Markdown fences.
3. Upload via REST API:

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

1. Read the page back and verify rendered storage contains the expected native macro (drawio, plantuml) or ac:image only for ordinary images.

Use native PlantUML storage for sequence diagrams and for non-sequence diagrams only when the PlantUML macro and its Graphviz dot dependency are confirmed working on the target Confluence instance:

<ac:structured-macro ac:name="plantuml">
  <ac:plain-text-body><![CDATA[
@startuml
component "Frontend\n/app" as UI
component "Backend API\n/service" as API
UI --> API : request\nwith details
@enduml
  ]]></ac:plain-text-body>
</ac:structured-macro>

PlantUML labels and relationship descriptions must stay syntactically valid. Do not put physical newlines inside quoted labels or edge labels; use escaped \n instead. For example, write component "Frontend\n/app" as UI, not a two-line component "Frontend label. Write UI --> API : request\nwith details, not a multi-line edge description.

After uploading native macros, read the page back and verify the expected ac:structured-macro ac:name="drawio", ac:structured-macro ac:name="plantuml", or ordinary-image ac:image exists. Treat empty macros, literal @startuml text, unexpected ac:macro ac:name="mermaid" output, rendered PlantUML Syntax Error, or Graphviz/dot errors as a failed upload/rendering workflow.

See Image Handling Best Practices for details.

###Patch Native Macro Storage Safely

For localized changes on pages with native macros (drawio, plantuml, layouts, complex tables), prefer storage-fragment patching over a full Markdown round trip. Use patch_storage_fragment.py or replace_macro_with_drawio.py in dry-run mode first, inspect the generated before/preview storage snapshots, then apply only after explicit confirmation. After applying, verify page version increased and read-back storage still contains required native macros.

See Storage Format for the validation checklist.

###Search, Create, and Update Pages

Use the REST scripts or the Confluence Python client from scripts/confluence_auth.py. Writes require an immediate dry-run/preview and explicit user confirmation.

###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:

##Utility Scripts

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