acs2md

acs2md stands for Atlassian Confluence Space to Markdown.

It is the space-scale export tool in the Climakers portfolio. Customers 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.

What it does

• Convert all pages in a Confluence space to Markdown in one 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 from the same binary when you need targeted follow-up work.

Why customers use it

Customers typically buy acs2md when the problem is not a single page but a documentation estate. The business need is usually continuity, migration, portability, compliance, AI ingestion, or governance at scale rather than one-off export convenience.

• 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.

Installation and First-Time Setup

If this is your first time with the product, start with setup before choosing a command.

The recommended onboarding flow is:

1. install the released binary for the target platform
2. verify the binary and confirm the installed version
3. activate the purchased license
4. configure Confluence access
5. run acs2md doctor
6. discover the target estate with space list and space pages
7. run the first real bulk export

Use Installation and First-Time Setup as the primary guide for new users. That page is written for customers who need to move from procurement and installation to a first successful, correctly scoped space export.

How to use this documentation

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 guide that matches the job:

• Installation and First-Time Setup for the first bulk run
• Configuration for connection and credential setup
• Convert Spaces for full-space Markdown export
• Extensions & Macros for supported Confluence extensions, macro rendering, and media handling at space scale
• Get Space Info for native payload retrieval
• List Spaces for discovery and inventory
• List Pages for scope and hierarchy confirmation
• Space Permissions for access review
• Space Properties for metadata inspection
• Workflows & Recipes for repeatable continuity, migration, and governance scenarios
• Utilities for doctor, tree, support, and completion

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

Supported extensions and macros

acs2md can render a wide range of Confluence extensions, marketplace macros, embeds, and media types across a full-space conversion. That includes draw.io and Roadmap Planner diagrams, page-listing macros such as Page Tree and Content by Label, people and activity macros such as Contributors and Task Report, document-control macros such as Page Signatures, QC document macros, inline cards, and Confluence-hosted media.

When an element still cannot be rendered with the data available for that run, acs2md preserves it as a safe HTML comment instead of silently dropping it.

Use Extensions & Macros for the supported categories, the exact rendering flags, and the space-scale caching behavior that helps repeated macro resolution stay efficient during a bulk export.

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. Progress output stays on stderr, so commands that pipe or redirect stdout remain usable for reporting and 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 customers 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.

Markdown is clear text. That is what makes the export portable, reviewable, and interoperable. If the exported corpus contains sensitive content, it should be handled with the same security controls used for other confidential business records.

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 5
5. confirm the scope with acs2md space pages by-key TEAMDOCS --format json --limit 10 or --tree
6. export the first space with acs2md space convert by-key TEAMDOCS --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
• support for creating a diagnostic bundle to share with Climakers support
• completion for shell completion setup
• config where for locating the active config file

Typical customer scenarios

Companion tool

For converting individual pages, see acp2md.