Best Practices for Using acs2md in Your Projects

acs2md works best when teams treat it like an operational system instead of a one-time conversion command. The docs reinforce that repeatedly: validate the machine, discover the target, choose the right mode, and collect useful evidence when something goes wrong.

That is what keeps bulk export boring in the best possible way.

1. Run doctor any time the environment changes

The utilities docs recommend doctor after license activation, after credential changes, before the first bulk export on a new machine, and before scheduled or customer-facing runs.

That is the right baseline:

acs2md doctor

It verifies:

• configuration file validity
• Confluence credentials
• live API connectivity
• license presence and validation
• machine identity
• current version and build metadata

If you skip that step, you move environment mistakes into the most expensive part of the workflow.

2. Discover scope before you convert anything

The getting-started and workflow docs both push discovery ahead of conversion. Keep that habit.

acs2md space list --format json --limit 5
acs2md space pages by-key DOCS --tree

Why it matters:

• it confirms you are exporting the right space
• it lets stakeholders review the hierarchy before the run
• it reduces accidental exports during migrations or customer work

When governance matters, extend that discovery surface:

acs2md space properties by-key DOCS --format json
acs2md space permissions by-key DOCS --resolve-users --format json

That pulls metadata and access context into the same export program.

3. Decide the output contract before picking flags

Teams often choose flags one by one. A better approach is to decide what the output directory must represent.

Examples:

• A live docs mirror: use --sync, keep --rewrite-links, store in a stable directory.
• A long-term archive: keep the default incremental behavior or pass --incremental explicitly.
• A RAG corpus: use --exclude-marks, often disable embedded images, keep scheduled refreshes predictable.
• A migration staging tree: include metadata so identifiers and dates stay visible.

The output contract should drive the flags, not the other way around.

4. Keep secrets out of shell history when you can

The configuration docs recommend a clean split:

• keep non-secret defaults in the config file
• inject secrets through environment variables when possible
• use CLI flags for per-run overrides and debugging

That is especially useful in CI/CD:

export ACS2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACS2MD_CONFLUENCE_USERNAME=$CONFLUENCE_USER
export ACS2MD_CONFLUENCE_API_TOKEN=$CONFLUENCE_TOKEN

If you need separate environments on one machine, use a custom --config-file instead of hand-editing the same config back and forth.

5. Choose a stable output directory for recurring jobs

State tracking depends on a stable directory because .convert-sync-state.json lives next to the exported Markdown.

That leads to two practical rules:

• keep the same --output-dir when you want changed-only refreshes
• avoid --conflict-resolution=versioned when you expect sync or incremental behavior to keep working, because a timestamped directory is not a stable home for the state file

This is a subtle point, but it directly affects whether later runs stay efficient.

6. Make logging and support bundles routine, not exceptional

Bulk jobs are easier to trust when they leave evidence.

acs2md space convert by-key DOCS --output-dir ./docs --log-file acs2md.log
acs2md support --log-file acs2md.log --output bundle.txt

The support bundle includes masked configuration, diagnostics, environment context, and recent logs. That is valuable even inside your own team before support ever gets involved.

7. Separate workflows by purpose

The workflows page is useful because it stops pretending one export profile fits every job.

Use different commands or destinations for different purposes:

• continuity copy: --sync
• archive-first retention: --incremental
• migration planning: space pages --tree, then space convert --include-metadata
• native engineering analysis: space get --format atlas_doc_format
• governance review: space list, space properties, space permissions

When the purpose changes, the output contract should change with it.

A short operator checklist

Before a real run, confirm all of this is true:

• doctor passes
• the correct space was confirmed with space list and space pages
• the mode is explicit when deletion behavior matters
• secrets are handled through config or environment variables, not copied into notes
• logs are enabled for recurring or consequential runs
• the target directory is stable enough for state tracking

If even one of those points is unclear, stop and fix it before the export.

How these practices map to ISO 27001 and SOC 2 controls

Each of the practices above is also a control statement an auditor can verify. If you operate inside an ISO 27001, ISO 27017, NIS 2, or SOC 2 program, this is how the seven practices line up:

The practical message is that there is no extra “compliance mode” to enable. The defensible workflow and the productive workflow are the same workflow when you choose the right defaults.

Final recommendation

The best acs2md practice is not a specific flag. It is operational discipline. The teams that get the most value from the tool are the ones that validate the workstation, confirm scope, choose the correct mirror-or-archive contract, and keep enough logging to explain what happened later.

That is how a conversion tool becomes a dependable documentation operation.