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:
- Author bracket tags:
[Author Name] SPEC | Feature -> feature
- Doc type prefixes:
SPEC |, PRD |, DOC | -> remove
- Phase numbers when a product name exists:
Phase 2 | Product Overview -> use product name
- 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
- Scan for raw HTML
<a> tags with data-* attributes (embedded media) - replace with markdown links
- Verify image references work (script downloads to
images/ subfolder automatically)
- 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:
- Fetch page HTML via REST API (
body.storage)
- Parse
<ac:link> tags with regex
- Resolve titles to URLs via API
- 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:
- No raw
<ac: tags — grep output for <ac: to catch unconverted Confluence macros
- No broken image refs — if
images/ folder exists, verify every  ref has a matching file
- Source header present — first non-blank line after
# Title should be > Source: [Confluence](...)
- 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