qa-aman/confluence-to-md

Confluence to Markdown

Pull Confluence pages into the local repo as clean markdown. The bundled script handles all the messy Confluence storage format edge cases (user mentions, complex tables, images, status badges) so you don't have to. Zero LLM tokens spent on the actual conversion.

Quick start

# Single page
python3 .claude/skills/confluence-to-md/scripts/confluence-to-md.py <page_id> <output_path>

# Batch (write a Python loop - don't run CLI commands one by one)
python3 scripts/batch-convert.py

The script auto-loads credentials from .env at the project root.

Workflow

Step 1: Get the page ID

Extract from the Confluence URL - it's the number in the path:

https://[your-instance].atlassian.net/wiki/spaces/[SPACE]/pages/1234567890/Page+Title
                                                                ^^^^^^^^^^ this

If the user gives a title instead of URL, search via API:

curl -s -u "$CONFLUENCE_EMAIL:$CONFLUENCE_TOKEN" \
  "$CONFLUENCE_BASE_URL/wiki/rest/api/content?spaceKey=[SPACE]&title=$(python3 -c 'import urllib.parse; print(urllib.parse.quote("Page Title"))')"

Step 2: Pick the output path

Follow your project's naming conventions. A common pattern:

| Content type | Path pattern | |---|---| | Feature specs | outputs/features/NNN-feature-name/feature-name.md | | Knowledge docs | inputs/knowledge/slugified-title.md | | Cross-functional | outputs/cross-functional/doc-name.md |

Folder naming - strip from Confluence titles:

1. Author bracket tags: [Author Name] SPEC | Feature -> feature
2. Doc type prefixes: SPEC |, PRD |, DOC | -> remove
3. Phase numbers when a product name exists: Phase 2 | Product Overview -> use product name
4. Use the feature/product concept name, not the page description

Step 3: Run the script

python3 .claude/skills/confluence-to-md/scripts/confluence-to-md.py 1234567890 outputs/features/001-my-feature/my-feature.md

Step 4: Post-conversion check

1. Scan for raw HTML <a> tags with data-* attributes (embedded media) - replace with markdown links
2. Verify image references work (script downloads to images/ subfolder automatically)
3. Check for excessive blank lines or formatting artifacts

Batch conversion

Write a Python driver script for multiple pages:

import subprocess
pages = {
    "1234567890": "outputs/000-topic-a/topic-a.md",
    "9876543210": "outputs/001-topic-b/topic-b.md",
}
for page_id, output_path in pages.items():
    subprocess.run(["python3", ".claude/skills/confluence-to-md/scripts/confluence-to-md.py", page_id, output_path], check=True)

Index files (zero LLM tokens)

For overview pages, don't convert - parse programmatically:

1. Fetch page HTML via REST API (body.storage)
2. Parse <ac:link> tags with regex
3. Resolve titles to URLs via API
4. Write structured markdown

What the script handles

The script automatically resolves these Confluence storage format quirks:

• <time datetime="..."/> self-closing tags
• <ri:user> mentions (resolves display names via API, cached)
• Bare <ac:link> without URLs (resolves from body.view)
• Complex tables with numberingColumn, colgroup, highlights
• Lists inside table cells (flattened to inline)
• Status macros -> [Yes]/[No] text
• Single-cell layout tables (unwrapped)
• <ac:image> attachments (downloaded to images/, handles CDN 302 redirects)

Snapshot auto-save — after every successful pull, the script saves a copy to .local/confluence-snapshots/<page_id>.md (auto-creates the folder). This baseline is the "last known sync" — every new pull overwrites it.

Preflight check before pushing back (sibling script)

Whenever you later push changes back to the same Confluence page, run the preflight FIRST to detect whether anyone edited that page on Confluence since your last pull. Without this check, you can silently overwrite other people's edits — a real-world incident that motivated this safeguard.

The preflight script lives inside this skill's scripts/ folder (and also inside md-to-confluence/scripts/ — both copies work identically):

python3 .claude/skills/confluence-to-md/scripts/confluence-preflight.py <page_id> <local.md>
# OR equivalently:
python3 .claude/skills/md-to-confluence/scripts/confluence-preflight.py <page_id> <local.md>

Exit codes:

• 0 — Safe to push
• 1 — CONFLICT: Confluence has edits your local .md is missing. STOP and merge
• 2 — Error (credentials, network, etc.)

Use --show-diff to see full diffs, --force only if you deliberately want to overwrite.

If something looks wrong in the output, read references/storage-format-gotchas.md for the full list of 12 known issues and their fixes.

Script location (IMPORTANT)

Scripts live INSIDE the skill folder, NOT in a shared .claude/scripts/ folder:

• Project: .claude/skills/confluence-to-md/scripts/confluence-to-md.py
• Global: ~/.claude/skills/confluence-to-md/scripts/confluence-to-md.py

NEVER use symlinks — always copy actual Python files. Symlinks break when the target moves.

Keep both locations in sync when modifying the script.

Post-conversion evals

After conversion, automatically verify:

1. No raw <ac: tags — grep output for <ac: to catch unconverted Confluence macros
2. No broken image refs — if images/ folder exists, verify every ![](images/...) ref has a matching file
3. Source header present — first non-blank line after # Title should be > Source: [Confluence](...)
4. No excessive blank lines — no more than 2 consecutive blank lines anywhere in the file

Dependencies

• Python 3 (standard library only)
• Pandoc (brew install pandoc)
• .env with: CONFLUENCE_EMAIL, CONFLUENCE_TOKEN, CONFLUENCE_BASE_URL