acp2md

acp2md stands for Atlassian Confluence Page to Markdown.

It is the focused single-page tool in the Climakers portfolio. Customers use it when the requirement is not “export the whole space,” but “work on this exact page with controlled scope, predictable output, and customer-owned downstream handling.”

What it does

• Convert one Confluence page to Markdown by page ID, title, or Confluence URL.
• Retrieve the same page in ADF or Storage format without converting it.
• Count ADF nodes and marks and list page properties when page-level analysis matters.
• Control metadata, image embedding, macro rendering, and output conflict behavior.
• Refresh recurring exports efficiently with a local .convert-sync-state.json file beside the output.
• Work with current, draft, archived, and historical versions of a page.

Why customers use it

Customers typically buy acp2md because one page can carry disproportionate business value. It might be a policy page, a regulated procedure, a recovery runbook, a handoff document, or a single authoritative knowledge asset that must move into Git, archival storage, or an AI workflow without dragging an entire Confluence estate along with it.

• Export one critical page for retention, legal review, or controlled evidence capture.
• Inspect native ADF or Storage output during migration design or troubleshooting.
• Pull an operational runbook or support procedure into Git under customer control.
• Build a curated RAG or search corpus from authoritative pages rather than a full space dump.
• Respond quickly when teams are sharing browser URLs and need an exact export without discovery overhead.

Installation and First-Time Setup

If this is your first time with the product, start with the setup path before you think about commands.

The recommended onboarding flow is:

1. install the released binary for your platform
2. verify the binary and confirm the installed version
3. activate the purchased license
4. configure Confluence access
5. run acp2md doctor
6. validate the target scope with space list and space pages
7. run the first real page export

Use Installation and First-Time Setup as the primary new-user guide. That page is written for customers who need to move from “we bought the tool” to “the first successful export completed correctly” without guessing the order of operations.

How to use this documentation

Read this overview first when you need to understand where acp2md fits in the Climakers toolset and which page workflow matches the job.

Then move to the guide that matches the operation you actually need:

• Installation and First-Time Setup for the first successful run
• Configuration for connection and credential setup
• Convert Pages for Markdown export workflows
• Extensions & Macros for supported Confluence extensions, macro rendering, and media handling
• Get Pages for native ADF or Storage retrieval
• Count & Analyze for structural ADF analysis
• Page Properties for metadata inspection
• Workflows & Recipes for customer-facing scenarios you can adapt directly
• Utilities for doctor, tree, support, and completion

That structure keeps this page focused on decision-making while the subpages hold the detailed command surface.

Supported extensions and macros

acp2md can render a wide range of Confluence extensions, marketplace macros, embeds, and media types rather than flattening them into opaque placeholders. That includes draw.io and Roadmap Planner diagrams, page-listing macros such as Page Tree and Recently Updated, 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 cannot be rendered with the context available for that run, acp2md 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 page-level context requirements for macros that depend on space-aware resolution.

Business outcomes

Backup and retention

acp2md helps customers create portable copies of business-critical pages in a vendor-neutral format. That matters when a team needs page-level backup, regulated evidence retention, or a reliable export before editing, deletion, or platform changes.

Business continuity and disaster recovery

For continuity planning, a standard Markdown export is easier to replicate, store, diff, and recover than a proprietary document representation. Teams can place exported pages in Git, encrypted archives, object storage, secondary regions, or internal repositories as part of a broader continuity strategy.

Compliance and audit support

Because the output is plain text with optional metadata, exported pages are easier to inspect, classify, archive, review, and compare over time. This supports audit evidence preparation, records governance, legal hold procedures, and internal control workflows.

RAG and LLM readiness

Confluence content is valuable, but not always directly usable by retrieval systems. acp2md converts pages into a format that is easier to chunk, embed, index, enrich, and govern for internal search, question-answering, and knowledge-assistant workflows.

Data sovereignty and clear-text ownership

Markdown is clear text by design. In this context, that is a feature.

• Your exported knowledge is no longer locked inside a proprietary editor format.
• You decide where the resulting files live: local disk, internal Git, approved cloud storage, regional object storage, backup vaults, or offline archives.
• You can apply your own controls around that content, including encryption at rest, access control, retention rules, DLP, object lock, legal hold, and regional residency requirements.
• You can inspect the content with standard tooling without depending on one platform to read your own documentation.

Important note: because the output is standard clear-text Markdown, sensitive exports should be stored in the same protected environments you use for other confidential business records.

Read-only by design: acp2md 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.

State file, sync, and incremental efficiency

Recurring page exports should not redownload unchanged content unnecessarily. That is why acp2md can keep a local .convert-sync-state.json file beside the output.

• --sync refreshes the page when it changes and removes the local file if the source page disappears from Confluence.
• --incremental refreshes the page when it changes but keeps the local file even if the source page later disappears.
• repeated exports remain practical for high-value pages that need controlled refresh over time.

This makes acp2md useful not only for one-off exports, but also for continuity-sensitive and archive-first page workflows.

First successful run

The standard first run is deliberately simple:

1. activate the license
2. configure Confluence access
3. run acp2md doctor
4. discover the space with acp2md space list
5. confirm the scope with acp2md space pages by-key DOCS --limit 25
6. export one page with acp2md page convert by-id 123456 -o ./page.md

That gives a clean operator path from environment validation to the first portable Markdown output.

Recommended operator flow

1. activate the license
2. configure Confluence access
3. run acp2md doctor
4. discover the correct space and page with space list and space pages
5. use tree --short when you want a compact command inventory before a customer-facing run
6. choose the right page command: convert, get, count, or properties

Choosing the right page command

Use page convert when

• you want readable Markdown output
• you want to store a page in Git, object storage, or a content pipeline
• you are preparing content for static sites, RAG, audits, or long-term retention

Use page get when

• you want native Confluence content instead of Markdown
• you need atlas_doc_format for engineering or migration analysis
• you need storage output for debugging or custom transformation work

Use page count when

• you want to estimate page complexity before migration
• you want to inspect formatting richness before AI ingestion or publishing
• you need a fast structural profile of headings, tables, lists, marks, or macros

Use page properties when

• you need page metadata rather than content
• you are investigating app-added properties, migration state, or governance metadata

Choose the input form deliberately

• by-id is the most deterministic choice when you already know the exact page.
• by-title is useful when the title is known but the page ID is not.
• by-url is the fastest option when support, compliance, or engineering teams are sharing browser links directly.

Shared operator utilities

acp2md also includes the supporting commands teams need around the export itself:

• doctor for environment validation
• tree --short for fast command discovery before a runbook or demo
• 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 bulk operations across an entire space, see acs2md, the space converter.