acs2md

acs2md stands for Atlassian Confluence Space to Markdown.

It is the space-scale export tool in the Climakers portfolio. Use it when the requirement is a governed documentation estate, a continuity copy, a migration payload, or a repeatable full-space workflow that has to remain operational over time.

Compatibility: acs2md supports Atlassian Confluence Cloud only. It does not support Confluence Server or Confluence Data Center.

Positioning: acs2md is not just a bulk conversion CLI. It is a tool for giving customers control, ownership, and portability over enterprise knowledge at space and documentation-estate scale.

What it does

• Convert all pages in a Confluence space to Markdown in a single command
• Preserve the space hierarchy as folders and files
• Rewrite internal Confluence links to local relative paths automatically
• Use sync and incremental workflows with .convert-sync-state.json to avoid reprocessing unchanged pages
• List accessible spaces and inspect page inventories, properties, and permissions
• Run page convert, page get, page count, and page properties commands from the same binary when you need targeted follow-up work

Why teams use it

• Maintain a current continuity copy of a full documentation space.
• Build a disaster recovery archive outside the source platform.
• Move a documentation estate into Git-based workflows without losing structure.
• Create a repeatable Markdown corpus for RAG, search, and internal assistants.
• Run inventory, access review, and metadata inspection from the same binary that performs the export.

How to use this manual

Read this overview first when you need to decide whether the requirement is a space-scale export, a governed synchronization workflow, or a supporting inventory or governance task.

Then move into the operational guides that match the job:

• Getting started for the first bulk run
• Configuration for connection and credential setup
• Space convert for full-space Markdown export
• Space get for native payload retrieval
• Space list for discovery and inventory
• Space pages for scope and hierarchy confirmation
• Space permissions for access review
• Space properties for metadata inspection
• Utilities for doctor, tree, and completion

That split keeps this page focused on operating model and decision-making, not on duplicating every command flag.

Progress tracking

Long-running operations display real-time progress bars on stderr so they do not interfere with piped stdout output.

• space convert shows conversion progress with the current page title and ETA.
• space get shows download progress for native payload exports.
• --resolve-users shows progress when resolving multiple account IDs to display names.

This keeps recurring export jobs observable without breaking automation.

Business outcomes

Backup and long-term retention

acs2md produces a space-wide Markdown export that is easier to store, replicate, diff, audit, and archive than a platform-bound representation. This supports internal backup strategies, documentation escrow, project closeout archives, and regulatory retention workflows.

Business continuity and disaster recovery

A continuity plan is stronger when operational knowledge can be recovered outside the source platform. acs2md helps teams maintain a current copy of a Confluence space in a format that can be restored, reviewed, republished, or searched independently of Confluence.

Compliance and governance

Plain-text exports with predictable file organization are useful for evidence collection, records management, internal controls, and audit support. Teams can apply retention labels, version control, access review, and immutable backup policies using the storage and governance tools they already trust.

RAG and LLM enablement

Markdown is a practical format for chunking, embedding, indexing, and retrieval. acs2md turns a Confluence space into a corpus that is easier to feed into enterprise AI workflows while preserving useful document structure such as headings, lists, tables, and metadata.

Data sovereignty and clear-text ownership

acs2md exports documentation into standard Markdown files that the customer can store and govern in the customer environment.

• The resulting files can stay in a customer-selected region, network boundary, or storage platform.
• The output is readable without a proprietary viewer.
• Standard tooling can be applied for encryption, DLP, legal hold, version control, backup, classification, and retention.
• Documentation can move between teams, repositories, backup systems, or cloud providers without format lock-in.

Read-only by design: acs2md only reads from Confluence. It never creates, modifies, or deletes any page, space, property, permission, or other resource in your Confluence instance. All API calls are read-only GET requests.

First successful bulk run

The standard first bulk run follows a predictable sequence:

1. activate the license
2. configure Confluence access
3. run acs2md doctor
4. list candidate spaces with acs2md space list --limit 25
5. confirm the scope with acs2md space pages by-key DOCS --limit 50 or --tree
6. export the first space with acs2md space convert by-key DOCS --output-dir ./docs-export

That flow validates the environment, confirms the target estate, and produces a portable Markdown export in one pass.

Recommended operator flow

1. activate the license
2. configure Confluence access
3. run acs2md doctor
4. discover the target with space list and space pages
5. use tree --short when you want a compact release inventory before a scheduled or customer-facing export
6. run space convert, space get, space properties, or space permissions

Choosing the right space command

Use space convert when

• you want a portable Markdown documentation set
• you are preparing a continuity copy, migration payload, static-site source, or RAG corpus
• you want hierarchy preservation and optional link rewriting

Use space get when

• you want native Confluence payloads rather than Markdown
• you are doing migration engineering or custom downstream processing
• you need raw atlas_doc_format or storage output for a whole space

Use space list when

• you need to discover available spaces first
• you are building an inventory or selecting the correct target scope
• you want structured output for reporting or pre-migration planning

Use space pages when

• you need to confirm the contents of a space before conversion
• you want to inspect hierarchy, page count, and page ordering
• you want to validate scope with a customer or stakeholder before a bulk run

Use space permissions or space properties when

• governance, audit, or access review matters
• you need supporting metadata around the space, not just the content itself

State file and sync efficiency

Recurring estate exports should not redownload unchanged content unnecessarily. That is why acs2md supports both --sync and --incremental workflows with .convert-sync-state.json:

• --sync refreshes changed pages and removes local files when the source page disappears from Confluence
• --incremental refreshes changed pages but keeps local files even if the source page is later removed

This makes the tool usable for both strict continuity mirrors and archive-first workflows.

Shared operator utilities

acs2md includes the same supporting commands that reduce operator friction in repeatable runs:

• doctor for environment checks
• tree --short for a compact inventory of the available command surface
• completion for shell completion setup
• config where for locating the active config file

Typical use cases

Companion tool

For converting individual pages, see acp2md.