Sync and Incremental

acp2md can maintain a local state file named .convert-sync-state.json beside the output file when you use page convert with --sync or --incremental. This makes repeat exports efficient by skipping pages whose content has not changed.

Both modes use the same state file and the same change-detection mechanism. The only difference is what happens when a page is removed from Confluence.

At a glance

How the state file works

When you run a convert command with either flag, acp2md:

1. Reads .convert-sync-state.json from the same directory as the output file
2. Checks the page version in Confluence against the version recorded in the state file
3. If the version is the same, skips the download and conversion entirely
4. If the version changed, downloads and re-converts the page, then updates the state file

The state file tracks the page ID, version number, version timestamp, output file path, and conversion timestamp for each page.

State file example

{
  "pages": {
    "4068212885": {
      "converted_at": "2026-04-05T13:47:56.649414+02:00",
      "version_created_at": "2025-07-29T09:27:19.031Z",
      "page_id": "4068212885",
      "title": "Git Signed Commits",
      "file_path": "site.md",
      "version_number": 50
    }
  },
  "version": 1
}

--sync mode

--sync is designed for live mirrors and continuity copies where the local output should always reflect the current state of Confluence. If a page is deleted in Confluence, the local file is also deleted.

First run

acp2md page convert by-id 4068212885 --sync --output site.md

🔄 Mode: sync — state file: .convert-sync-state.json

The page is downloaded, converted to Markdown, saved to site.md, and the state file is created.

Second run (unchanged)

acp2md page convert by-id 4068212885 --sync --output site.md

🔄 Mode: sync — state file: .convert-sync-state.json
✅ Page is up-to-date, skipping conversion.

No API call to download the page content is made. Only the version metadata is checked.

When a page is removed

If the page no longer exists in Confluence, --sync deletes the local site.md file and removes the entry from the state file.

When to use --sync

• Continuity copies that must match the current Confluence state
• Scheduled exports that feed a downstream system expecting a clean mirror
• CI/CD pipelines where stale local files would cause problems

--incremental mode

--incremental is the default mode. It is designed for archive-oriented workflows where local files should be preserved even if the source page is deleted from Confluence.

First run

acp2md page convert by-id 4068212885 --incremental --output site.md

🔄 Mode: incremental — state file: .convert-sync-state.json

Behaves the same as --sync on first run: the page is downloaded, converted, and the state file is created.

Second run (unchanged)

acp2md page convert by-id 4068212885 --incremental --output site.md

🔄 Mode: incremental — state file: .convert-sync-state.json
✅ Page is up-to-date, skipping conversion.

Same skip behavior as --sync.

When a page is removed

If the page no longer exists in Confluence, --incremental keeps the local site.md file on disk. The entry is removed from the state file tracking, but the exported Markdown is preserved.

When to use --incremental

• Compliance and audit archives that must retain exported content regardless of source changes
• Legal hold workflows where deletion of evidence is not acceptable
• Historical records where you want a snapshot that survives upstream deletions

Mutual exclusivity

--sync and --incremental are mutually exclusive. You cannot use both in the same command.

# ✅ Valid
acp2md page convert by-id 123456 --sync --output page.md
 
# ✅ Valid
acp2md page convert by-id 123456 --incremental --output page.md
 
# ❌ Invalid — mutually exclusive
acp2md page convert by-id 123456 --sync --incremental --output page.md

Choosing the right mode