Workflows & Recipes

This page collects practical acp2md workflows for customers who already understand the product and now need a repeatable way to apply it in real operational situations.

Controlled retention export

Use this pattern when legal, compliance, or records teams need one exact page captured in a durable format.

acp2md page convert by-id 123456 \
  --include-metadata \
  --output retention/policy-123456.md

Why this workflow matters:

• one page can be retained without exporting a whole space
• the metadata block preserves identifiers and version context
• the result can move into Git, vault storage, or an evidence archive

Runbook export to Git

Use this when an operations or support team wants a runbook under normal source control.

acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/OPS/pages/123456/Runbook" \
  --output docs/runbooks/service-runbook.md \
  --sync

Why this workflow matters:

• the URL form is convenient for operators working from shared browser links
• --sync keeps the checked-in copy aligned with the source page
• the output is already in Markdown and can go straight into repository review workflows

Recurring page export with archive-first retention

Use this when a team needs to refresh a high-value page over time but still keep the last local copy even if the source page is later removed from Confluence.

acp2md page convert by-id 123456 \
  --output archive/policy-123456.md \
  --incremental

Why this workflow matters:

• the local .convert-sync-state.json file allows repeat runs to refresh only when the page changed
• --incremental preserves the local file if the source page later disappears
• the result behaves more like a controlled archive than a strict live mirror

Migration analysis on a difficult page

Use this when the team needs to understand exactly what is inside a heavily formatted page before migration.

acp2md page get by-id 123456 -f atlas_doc_format > analysis/page-123456-adf.json
acp2md page count nodes by-id 123456 > analysis/page-123456-nodes.json
acp2md page count marks by-id 123456 > analysis/page-123456-marks.json

Why this workflow matters:

• ADF retrieval exposes the native page structure
• node and mark counts help estimate layout and formatting complexity
• the team can decide early whether a custom migration rule is needed

Curated source for RAG or search

Use this when you need one authoritative source page in a cleaner, lighter form for downstream AI pipelines.

acp2md page convert by-id 123456 \
  --exclude-marks \
  --embed-images=false \
  --output rag/customer-policy.md

Why this workflow matters:

• plain-text oriented output is easier to chunk and index
• external image references keep the file smaller
• curated page selection produces higher signal than a broad dump

Draft capture before publishing

Use this when a team needs a point-in-time copy of an unpublished draft before an approval or release decision.

acp2md page convert by-id 123456 \
  --get-draft \
  --output archive/draft-123456.md

Why this workflow matters:

• the team captures the pre-publication state of the page
• the export can be reviewed outside Confluence
• change-management or approval records can include the exact draft content

Support-ready diagnostic workflow

Use this when a customer run fails and the issue needs escalation with enough detail for troubleshooting.

acp2md doctor
acp2md support --output support/acp2md-support.zip

Why this workflow matters:

• doctor gives the fastest readiness summary
• the support bundle captures environment, config, diagnostics, and masked variables in one package
• the escalation starts with evidence instead of guesswork

Back up a critical page and put it back

Use this for runbooks, policies or other pages that must be recoverable into Confluence itself. Available from v1.0.12.

# Back up the page with its attachments
acp2md page get by-id PAGE_ID -o ./backups/runbook.json --attachments-dir ./backups/attachments
 
# Later: does Confluence still hold it as backed up?
acp2md page check --file ./backups/runbook.json --attachments-dir ./backups/attachments
 
# It was deleted or overwritten: review the plan, then restore
acp2md page restore --file ./backups/runbook.json --attachments-dir ./backups/attachments --dry-run
acp2md page restore --file ./backups/runbook.json --attachments-dir ./backups/attachments

Why this workflow matters:

• the backup holds the body, title, parent, version, labels and attachment files
• page check says exactly what differs before anything is written
• page restore reverts an edited page to its backed-up version, keeping its history, or recreates a deleted one

Business continuity plan evidence

Use this for the handful of pages a continuity plan names explicitly — the incident runbook, the recovery procedure, the contact list — when the plan has to show they are backed up, current and restorable (ISO/IEC 27001:2022 A.8.13 and A.5.30, SOC 2 A1.3, NIS 2 Article 21(2)(c), ISO 9001:2015 clause 7.5.3). Climakers is not certified under these frameworks; the files are the evidence you present.

# 1. Back up each named page with its attachments
acp2md page get by-id PAGE_ID -o ./bcp/runbook.json --attachments-dir ./bcp/attachments
 
# 2. Verify on a schedule, and keep the result
acp2md page check --file ./bcp/runbook.json --attachments-dir ./bcp/attachments --fail-on-drift -f json > ./bcp/runbook.check.json
 
# 3. Test recovery into an archive space without touching the original
acp2md page restore --file ./bcp/runbook.json --attachments-dir ./bcp/attachments --space-key BCPTEST --title "Runbook (recovery test)" --yes
 
# 4. Keep a readable copy where people can open it without Confluence
acp2md page convert by-id PAGE_ID -o ./continuity/runbook.md --include-metadata

• the JSON check result names what differs — state, version, body, attachments, labels — and the non-zero exit is the alert
• the recovery test proves the backup restores, with attachments, into a page people can open; remove the test page afterwards in Confluence, since restore never deletes
• for a whole space, use acs2md: Business continuity plan evidence

Recommended sequence for customer-facing runs

1. confirm workstation readiness with doctor
2. validate page scope with space list and space pages
3. pick the right page input form: ID, title, or URL
4. decide whether the output is for retention, Git, migration analysis, or AI ingestion
5. choose --sync or --incremental deliberately when writing to files repeatedly