Convert Spaces

The space convert commands export an entire Confluence space — all its pages — to a directory of Markdown files. The page hierarchy is automatically preserved as nested subdirectories.

This is the main operational workflow for acs2md and the core reason most teams license the product.

Convert by key

acs2md space convert by-key SPACE_KEY [flags]

The space key is the short identifier visible in the Confluence URL: .../wiki/spaces/MYSPACE/. It is also shown in the output of acs2md space list.

Examples

# Convert to the default output directory
acs2md space convert by-key MYSPACE
 
# Convert to a specific directory
acs2md space convert by-key MYSPACE --output-dir ./docs
 
# Build a RAG knowledge base — plain text, no images
acs2md space convert by-key MYSPACE \
  --exclude-marks=true \
  --embed-images=false \
  --output-dir ./rag-knowledge-base
 
# Include only currently published pages
acs2md space convert by-key MYSPACE --status current --output-dir ./docs
 
# Disable internal link rewriting
acs2md space convert by-key MYSPACE --rewrite-links=false --output-dir ./site
 
# Incremental sync — only re-convert changed pages, keep deleted files
acs2md space convert by-key MYSPACE --incremental --output-dir ./docs
 
# Full sync — re-convert changed pages, delete files for removed pages
acs2md space convert by-key MYSPACE --sync --output-dir ./docs

Flags

Convert by ID

acs2md space convert by-id SPACE_ID [flags]

Converts a space identified by its numeric ID instead of its key. Same flags as by-key.

acs2md space convert by-id 65539 --output-dir ./docs

Conversion flags

These flags are available on both by-key and by-id and control how each page is rendered.

Content & metadata

Images & media

Obsidian & output style

Extension flags

Throughput

space convert converts 4 pages at once by default. Conversion is network-bound — several API calls per page — so overlapping a few pages hides most of the per-page latency.

# Raise it for a large space on a tolerant tenant
acs2md space convert by-key DEVOPS --output-dir ./docs --concurrency 8
 
# Restore strictly sequential conversion
acs2md space convert by-key DEVOPS --output-dir ./docs --concurrency 1

The useful ceiling is your Confluence tenant’s rate limit, not the number of CPU cores, which is why the default is deliberately modest. Raising it is safe because the HTTP client honours the Retry-After header: when Confluence answers a throttled request with 429 or 503 and names a delay, the client waits exactly that long rather than guessing. The server sets the pace instead of the client discovering it by failing.

Each command also reports how long it took:

✅ Sync complete!
  ✅ Converted: 835
  ❌ Failed: 0
  🔗 Links rewritten: 835 files
  📂 Output: ~/tmp/docs-sec-obsidian/SEC
  ⏱️  Took: 2m 14s

The figure covers the whole command, API calls and image downloads included.

Progress reporting

Long-running conversions display a real-time progress bar on stderr showing the current page title, completion percentage, and estimated time remaining. This does not interfere with stdout output that may be piped to a file.

That separation matters for automation because it keeps progress visibility for humans without corrupting redirected output.

If you need a clean transcript for CI logs, demos, or docs capture, use the global --no-progress flag.

Observed conversion run (sanitized)

The following output was captured from a live macOS run against a small current space, with the space name and key anonymized:

📚 Converting space: Team Documentation (TEAMDOCS)
📂 Output directory: /tmp/acs2md-doc-sample

🔄 Mode: incremental — state file: /tmp/acs2md-doc-sample/.convert-sync-state.json

🔍 Fetching page metadata for sync...
  📥 Fetched metadata for 6 pages ✅

📋 Found 6 page(s) to convert (0 up-to-date)

✅ Sync complete!
  ✅ Converted: 6
  ❌ Failed: 0
  ✅ Up-to-date (skipped): 0
  🗑️  Removed from tracking: 0
  🔗 Links rewritten: 1 files
  📂 Output: /tmp/acs2md-doc-sample

Running the same command again against the existing output directory produced:

📚 Converting space: Team Documentation (TEAMDOCS)
📂 Output directory: /tmp/acs2md-doc-sample

🔄 Mode: incremental — state file: /tmp/acs2md-doc-sample/.convert-sync-state.json

🔍 Fetching page metadata for sync...
  📥 Fetched metadata for 6 pages ✅

✅ All pages are up-to-date.

✅ Sync complete!
  ✅ Up-to-date (skipped): 6
  🗑️  Removed from tracking: 0
  📂 Output: /tmp/acs2md-doc-sample

Space plus page workflows

acs2md also includes page-level commands so teams can combine bulk export with targeted inspection from the same binary.

• acs2md page convert by-id, by-title, by-url
• acs2md page get by-id, by-title, by-url
• acs2md page count nodes, page count marks, and page properties

Output structure

acs2md creates subdirectories that mirror the Confluence page tree. Each page becomes a Markdown file, and child pages are placed inside a folder named after their parent.

./output/TEAMDOCS/
├── .convert-sync-state.json
├── Team_Documentation.md
└── Team_Documentation/
  ├── Architecture_decisions.md
  ├── Change_log.md
  ├── Meeting_notes.md
  ├── Product_requirements.md
  └── Retrospectives.md

File names are derived from page titles, with conflicts resolved using the --conflict-resolution strategy.

The root Markdown file and the child folder sharing the same page title are not theoretical; that layout came directly from a live export.

Output conflict resolution

When two pages in the space produce the same file name, --conflict-resolution controls the behaviour:

Sync and incremental mode

On the current live release tested for this documentation, acs2md space convert by-key defaults to incremental mode when neither --incremental nor --sync is passed. The tool creates a .convert-sync-state.json file inside the output directory and only re-converts pages that have changed since the last run.

The two flags are mutually exclusive.

Sample state file

The state file created by the live export looked like this after anonymization:

{
  "last_sync_at": "2026-03-29T10:55:33.744109+02:00",
  "pages": {
    "100101": {
      "converted_at": "2026-03-29T10:55:31.313290+02:00",
      "version_created_at": "2024-01-15T09:00:00.000Z",
      "page_id": "100101",
      "title": "Team Documentation",
      "file_path": "/tmp/acs2md-doc-sample/Team_Documentation.md",
      "version_number": 3
    }
  },
  "space_id": "100001",
  "version": 1
}

Recommended usage patterns

• Use --sync when the output directory should remain an exact live mirror of the source space.
• Use --incremental when you want a continuity or archive-style copy that keeps deleted content locally.
• Use --rewrite-links=false only when local portability is not required.
• Run space pages --tree before the first large export if you need to verify scope with stakeholders.

Practical examples

Full space migration for a static site

acs2md space convert by-key DOCS \
  --include-metadata \
  --output-dir ./site/docs

AI knowledge base (plain text, no images)

acs2md space convert by-key KB \
  --exclude-marks \
  --embed-images=false \
  --ext-render-toc=false \
  --output-dir ./rag

Nightly backup via CI/CD

#!/bin/bash
export ACS2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACS2MD_CONFLUENCE_USERNAME=$CONFLUENCE_USER
export ACS2MD_CONFLUENCE_API_TOKEN=$CONFLUENCE_TOKEN
 
acs2md space convert by-key DOCS \
  --output-dir "./backup/$(date +%Y-%m-%d)" \
  --log-file acs2md.log

Incremental sync in CI/CD

# Only re-convert changed pages, keep files for removed pages
acs2md space convert by-key DOCS \
  --incremental \
  --output-dir ./docs
 
# Only re-convert changed pages, delete files for removed pages
acs2md space convert by-key DOCS \
  --sync \
  --output-dir ./docs

Archive-oriented export that keeps removed pages

acs2md space convert by-key DOCS \
  --incremental \
  --output-dir ./archive/docs

Export without link rewriting

# Keep original Confluence URLs instead of rewriting to local paths
acs2md space convert by-key MYSPACE \
  --rewrite-links=false \
  --output-dir ./export

For scenario-driven guidance instead of single commands, continue with Workflows & Recipes.