Introduction to acs2md: What It Is and Why It Is Useful for Developers

acs2md is the bulk space converter in the Climakers portfolio. It is built for the moment when a team stops asking, “How do we export this page?” and starts asking, “How do we move or preserve this whole documentation estate without losing control?”

That distinction matters. A single-page export tool solves a local problem. A space-scale converter solves migration, continuity, compliance, governance, and AI-ingestion work that has to stay operational over time.

acs2md in one sentence

acs2md converts an entire Atlassian Confluence Cloud space into Markdown while preserving page hierarchy, rewriting internal links, and tracking future refreshes through .convert-sync-state.json.

In practice, that means one tool can help you:

• maintain a current continuity copy outside Confluence
• stage a docs-as-code migration into Git
• build a repeatable Markdown corpus for RAG or enterprise search
• inspect permissions, properties, and page inventories before you export anything
• keep later runs efficient by skipping pages that did not change

Why developers care about it

Most teams do not license a space converter because they love conversion. They do it because a larger workflow is blocked.

Typical developer-side reasons include:

• A static-site migration needs structure, not a pile of flat files.
• A Git repository needs local links that still work after export.
• A RAG pipeline needs repeatable Markdown rather than a proprietary viewer format.
• A continuity plan needs a local copy that can be reviewed, backed up, and audited outside the source platform.
• A migration program needs discovery commands before anyone commits to a bulk run.

The docs position acs2md as a space-scale tool for continuity, migration payloads, governed exports, and documentation-estate portability. That is a much more useful framing than “bulk export CLI.”

What acs2md actually covers

acs2md is broader than space convert. The operational surface is closer to a small toolkit:

That command split is useful because real migrations are rarely just one command. Operators need readiness checks, scope validation, and follow-up inspection before and after the export.

Why this matters for compliance and continuity programs

If your team operates inside a regulated environment, acs2md is also the artifact that turns Confluence content into evidence. Several of the controls your auditors care about ask for the same thing: a current, restorable, inspectable copy of documented information that does not depend on the source platform being available.

• ISO 9001:2015 clause 7.5 requires that documented information is controlled, current, and retrievable. A Markdown estate in Git satisfies the “control of documented information” requirement without locking the record inside a vendor portal.
• ISO/IEC 27001:2022 A.5.30 (ICT readiness for business continuity) and A.8.13 (information backup) ask for tested recovery and repeatable backups. A scheduled acs2md space convert --sync run is exactly that.
• ISO/IEC 27017:2015 CLD.12.1.5 addresses cloud-customer operational security. Read-only GET access to Confluence Cloud, executed from your own automation, is the kind of admin-side control the standard expects.
• NIS 2 Article 21(2)(c) requires business continuity, backup management, and crisis management for essential and important entities. A Git-tracked copy gives you the artifact and the audit trail in one move.
• SOC 2 Availability (A1.2 and A1.3) asks for backup processes and recovery testing. Tagged commits act as restore points and acs2md doctor produces evidence that the recovery path still works.

This is why the docs talk about continuity, governance, and AI ingestion in the same breath: in a regulated documentation estate, those are the same workflow.

The moment acs2md becomes the right fit

Use acs2md when the question is about a whole documentation estate.

That includes:

• docs-as-code migrations where hierarchy must survive
• continuity copies that need recurring refreshes
• archive programs that should outlive Confluence deletions
• RAG or search ingestion where Markdown should be regenerated on schedule
• governance work where permissions and metadata matter as much as page bodies

If the requirement is one exact page, acp2md remains the sharper tool. The acs2md docs say that directly, and the distinction is sensible: space workflows and page workflows are not the same operational problem.

Boundaries worth knowing early

The current docs make a few guardrails explicit:

• acs2md supports Confluence Cloud only
• released builds are currently available for macOS and Linux
• the tool is read-only by design and uses GET requests against Confluence
• long-running jobs show progress on stderr so stdout can stay useful for automation

Those are not marketing details. They tell you whether the tool fits your platform, your security model, and your pipeline conventions before you invest time in rollout.

A realistic first operator flow

The recommended first run is not guesswork. The customer docs and the GitHub manual line up around a predictable sequence:

acs2md doctor
acs2md space list --format json --limit 5
acs2md space pages by-key TEAMDOCS --tree
acs2md space convert by-key TEAMDOCS --output-dir ./docs --rewrite-links

That flow does four important things in order:

1. proves the workstation is ready
2. confirms the target space is the right one
3. shows the hierarchy before conversion
4. produces a portable Markdown tree with local links

That is exactly the kind of operator discipline teams need when a conversion job is tied to migration windows, customer reviews, or backup commitments.

Why the state file matters more than it looks

acs2md uses .convert-sync-state.json to compare current page versions against earlier runs. That lets later exports skip unchanged content and only re-convert what moved.

This matters because the tool is not just for one-time migration. It is also designed for repeatable maintenance workflows.

That one file is what makes these two modes possible:

• --sync for live mirrors that delete local files when source pages disappear
• --incremental for archive-style exports that keep local files after upstream deletion

Both patterns show up constantly in real documentation programs.

Final recommendation

Treat acs2md as a control and portability tool for Confluence estates, not just as a converter. If your team needs repeatable space exports, local ownership of documentation, or a Markdown corpus that can feed Git, compliance, or AI workflows, acs2md is the right place to start.

Read the overview first, then move directly into the getting-started guide and the sync vs incremental docs. That sequence gets you from product positioning to an actual operator-grade workflow without wasting a run.