Workflows & Recipes

This page collects practical acs2md workflows for customers who need repeatable, estate-scale operations rather than one-off command examples.

Continuity copy of a live space

Use this when the customer wants a current Markdown copy of a space outside the source platform.

acs2md space convert by-key DOCS \
  --output-dir ./continuity/docs \
  --sync

Why this workflow matters:

• --sync keeps the output aligned with the live source space
• the directory tree is usable outside Confluence immediately
• the customer gets a continuity copy that can be reviewed, backed up, and republished elsewhere

Archive-first export that keeps deleted content

Use this when the goal is preservation rather than strict mirroring.

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

Why this workflow matters:

• deleted Confluence pages stay in the local archive
• only changed pages are reprocessed on later runs
• the output behaves more like a long-term archive than a live mirror

Migration preparation before a platform move

Use this when the team needs a portable content tree before static-site migration or repository-based publishing.

acs2md space pages by-key DOCS --tree
acs2md space convert by-key DOCS \
  --include-metadata \
  --output-dir ./migration/docs

Why this workflow matters:

• space pages --tree validates the expected scope first
• metadata helps preserve identifiers during migration planning
• the directory structure is easier to map into target platforms

Native payload export for migration engineering

Use this when the team needs raw Confluence payloads for custom transformation, migration debugging, or engineering analysis before deciding how Markdown conversion should be handled.

acs2md space get by-key DOCS \
  --format atlas_doc_format \
  --output-dir ./native/docs

Why this workflow matters:

• native payload export preserves the source representation without converting it first
• engineering teams can inspect ADF or storage output before building custom migration rules
• the same binary still covers later bulk Markdown conversion when the workflow is ready to move forward

Broad Markdown corpus for RAG or enterprise search

Use this when the customer wants repeatable estate-scale content for AI ingestion or search indexing.

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

Why this workflow matters:

• a whole space can be converted into a consistent Markdown corpus
• plain-text oriented output is easier to chunk and index
• recurring runs can refresh the corpus without reprocessing unchanged pages

Governance and access review

Use this when permissions and metadata matter as much as the content itself.

acs2md space list --format json > governance/spaces.json
acs2md space properties by-key DOCS --format json > governance/docs-properties.json
acs2md space permissions by-key DOCS --resolve-users --format json > governance/docs-permissions.json

Why this workflow matters:

• inventory, metadata, and permission data can be captured together
• --resolve-users improves stakeholder readability for review outputs
• the workflow supports audits, cleanup, and migration governance work

Scheduled export for operations teams

Use this when the export must run on a schedule with minimal operator intervention.

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 ./scheduled/docs \
  --sync \
  --log-file acs2md.log

Why this workflow matters:

• environment variables keep secrets out of the command line history
• sync behavior is explicit and predictable
• logging creates an audit trail for recurring operational runs

Backup and disaster recovery into Confluence

Use this when lost content must come back into Confluence itself, not only into files. Available from v1.0.12.

# Every night: a restorable backup; unchanged pages are skipped
acs2md space get by-key DOCS --output-dir /backups --log-file backup.log
 
# Every morning: did anything change, disappear or land in the trash?
acs2md space check by-key DOCS --backup-dir /backups --fail-on-drift
 
# When something was lost: review the plan, then restore
acs2md space restore by-key DOCS --backup-dir /backups/DOCS --dry-run
acs2md space restore by-key DOCS --backup-dir /backups/DOCS
 
# Confirm the restore
acs2md space check by-key DOCS --backup-dir /backups/DOCS

Why this workflow matters:

• the backup holds everything a restore needs: bodies, attachments, labels, properties and the folder tree
• space check turns “something is missing” into a list of exactly what, before anyone writes anything
• the restore shows its plan, never deletes, and resumes if interrupted
• one page is a one-command recovery: acs2md page restore --backup-dir /backups/DOCS --page-id PAGE_ID

See Restore a Space for modes, what comes back and what cannot.

Business continuity plan evidence

Use this when an auditor or a continuity plan asks for proof, not a description: that a copy of the space exists outside Confluence, that it is current, and that recovery has been tested. The commands below produce that proof as files; map them to the controls your plan cites — ISO/IEC 27001:2022 A.5.29, A.5.30 and A.8.13, the SOC 2 availability criteria (A1.3 asks for tested recovery), NIS 2 Article 21(2)(c) on backup management and disaster recovery, ISO 9001:2015 clause 7.5.3 on documented information. Climakers is not certified under these frameworks; the artefacts are yours to present.

# 1. Nightly: a restorable native backup, kept with its log
acs2md space get by-key DOCS --output-dir /backups --log-file /backups/DOCS.log
 
# 2. Nightly, after the backup: verify it and keep the machine-readable result
acs2md space check by-key DOCS --backup-dir /backups --fail-on-drift -f json > /backups/DOCS.check.json
 
# 3. Quarterly: a recovery test into a scratch space, without touching the original
acs2md space restore by-key DOCS-DR --backup-dir /backups/DOCS --create-space --mode all --yes
acs2md space check by-key DOCS-DR --backup-dir /backups/DOCS --all -f json > /backups/DOCS-DR.test.json
 
# 4. Weekly: a readable continuity copy for the people who need it when Confluence is down
acs2md space convert by-key DOCS --output-dir /continuity --sync

What each step evidences:

• step 1 is the backup itself, with attachments, labels, properties and the folder tree recorded in .backup-manifest.json
• step 2 is backup verification: the JSON names every page that drifted, and a non-zero exit is the alert
• step 3 is the recovery test the SOC 2 and NIS 2 wording asks for: the restored copy is compared with the backup it came from, and the .restore-state.json left in the backup directory records what was restored and when
• step 4 is the copy that stays readable without Confluence, in Git, an archive or a static site

Two cautions: the recovery test leaves the progress file pointing at the scratch space, so a real restore into DOCS needs --reset-state; and restore never deletes anything, so the scratch space is retired by hand in Confluence. Keep /backups on storage you control and retain the .check.json and .test.json files for your retention period. See Restore a Space for what a restore can and cannot bring back.

Recommended sequence for customer-facing runs

1. confirm readiness with doctor
2. discover scope with space list and space pages
3. decide whether the output should behave like a mirror or an archive
4. choose whether link rewriting and embedded images help or hurt the downstream use case
5. treat permissions and properties as part of the export program when governance matters