---
name: sync-confluence
description: This skill should be used when syncing local markdown documentation to Confluence Cloud pages. It handles first-time setup (creating mapping files and docs directories), pushing updates to existing pages, and creating new pages with interactive destination prompts. Triggers on "sync to confluence", "push docs to confluence", "update confluence pages", "create a confluence page", or any request to publish markdown content to Confluence.
allowed-tools: Read, Bash(find *), Bash(source *), Bash(uv run *)
---

# Sync Confluence

Sync local markdown files to Confluence Cloud pages via REST API. Handles the full lifecycle: first-time project setup, page creation, and bulk updates.

## Prerequisites

Two environment variables must be set (typically in `~/.zshrc`):

- `CONFLUENCE_EMAIL` — Atlassian account email
- `CONFLUENCE_API_TOKEN_WRITE` — Atlassian API token with write scope (falls back to `CONFLUENCE_API_TOKEN`)

Generate tokens at: https://id.atlassian.com/manage-profile/security/api-tokens

The script requires `uv` to be installed. Dependencies (`markdown`, `requests`, `truststore`) are declared inline via PEP 723 and resolved automatically by `uv run`.

## Workflow

### 1. Check for Mapping File

Before running the sync script, check whether a `.confluence-mapping.json` exists in the project:

```bash
find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -name ".confluence-mapping.json" -maxdepth 3 2>/dev/null
```

- **If found** — skip to step 3 (Sync).
- **If not found** — proceed to step 2 (First-Time Setup).

### 2. First-Time Setup

When no mapping file exists, gather configuration interactively via `AskUserQuestion`:

1. **Confluence base URL** — e.g., `https://myorg.atlassian.net/wiki`
2. **Space key** — short identifier in Confluence URLs (e.g., `ZR`, `ENG`)
3. **Parent page ID** — the page under which synced pages nest. Tell the user: "Open the parent page in Confluence — the page ID is the number in the URL."
4. **Parent page title** — prefix for generated page titles (e.g., `ATS Platform`)
5. **Docs directory** — where markdown files live relative to repo root (default: `docs/`)

Then create the docs directory and mapping file:

```python
import json
from pathlib import Path

config = {
    "confluence": {
        "cloudId": "<domain>.atlassian.net",
        "spaceId": "",
        "spaceKey": "<SPACE_KEY>",
        "baseUrl": "<BASE_URL>"
    },
    "parentPage": {
        "id": "<PARENT_PAGE_ID>",
        "title": "<PARENT_TITLE>",
        "url": "<BASE_URL>/spaces/<SPACE_KEY>/pages/<PARENT_PAGE_ID>"
    },
    "pages": {},
    "unmapped": [],
    "lastSynced": ""
}

docs_dir = Path("<REPO_ROOT>") / "<DOCS_DIR>"
docs_dir.mkdir(parents=True, exist_ok=True)
mapping_path = docs_dir / ".confluence-mapping.json"
mapping_path.write_text(json.dumps(config, indent=2) + "\n")
```

To discover `spaceId` (required for page creation), run:

```bash
source ~/.zshrc && curl -s -u "${CONFLUENCE_EMAIL}:${CONFLUENCE_API_TOKEN_WRITE}" \
  -H "X-Atlassian-Token: no-check" \
  "<BASE_URL>/rest/api/space/<SPACE_KEY>" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])"
```

Update the mapping file with the discovered spaceId before proceeding.

### 3. Sync — Running the Script

The sync script is at `${CLAUDE_PLUGIN_ROOT}/skills/sync-confluence/scripts/sync_confluence.py`.

**Always source shell profile before running** to load env vars:

```bash
source ~/.zshrc && uv run ${CLAUDE_PLUGIN_ROOT}/skills/sync-confluence/scripts/sync_confluence.py [options]
```

#### Common Operations

| Command | What it does |
|---------|-------------|
| _(no flags)_ | Sync all markdown files in docs dir |
| `--dry-run` | Preview changes without API calls |
| `--file docs/my-doc.md` | Sync a single file |
| `--update-only` | Only update existing pages, skip unmapped files |
| `--create-only` | Only create new pages, skip existing |
| `--mapping-file path/to/file` | Use a specific mapping file |
| `--docs-dir path/to/dir` | Override docs directory |

### 4. Creating a New Confluence Page

When the user wants to create a new page:

1. Ask for the page topic/title
2. Create the markdown file in the docs directory with a `# Title` heading and content
3. Run the sync script with `--file` pointing to the new file
4. The script detects the unmapped file, creates the page, and updates the mapping

**Title resolution order:** First `# H1` from the markdown → filename-derived title → raw filename. Titles are prefixed with the parent page title (e.g., `My Project: New Page`).

### 5. Mapping File Structure

```json
{
  "confluence": {
    "cloudId": "myorg.atlassian.net",
    "spaceId": "1234567890",
    "spaceKey": "ZR",
    "baseUrl": "https://myorg.atlassian.net/wiki"
  },
  "parentPage": {
    "id": "123456789",
    "title": "My Project",
    "url": "https://..."
  },
  "pages": {
    "my-doc.md": {
      "pageId": "987654321",
      "title": "My Project: My Doc",
      "url": "https://..."
    }
  },
  "unmapped": [],
  "lastSynced": "2026-03-03"
}
```

The script updates this file after each successful sync. Do not manually edit page entries unless correcting a known error.

## Technical Notes

- **Auth:** Confluence REST API v1 with Basic Auth + `X-Atlassian-Token: no-check`. Some Cloud instances block v2 or require this XSRF bypass.
- **Content format:** Markdown converted to Confluence storage format (XHTML) via Python `markdown` library with tables, fenced code, and TOC extensions.
- **SSL:** `truststore` delegates cert verification to the OS trust store, handling corporate SSL proxies (Zscaler, etc.).
- **Rate limiting:** Automatic retry with backoff on 429 and 5xx responses.
- **Sync timestamp:** `> **Last synced to Confluence**: YYYY-MM-DD` injected into the Confluence copy only. Local files are untouched.
- **Versioning:** Page versions auto-increment. The script GETs the current version before PUTting.