The ultimate guide to migrating Confluence to Docs-as-Code without losing your formatting

Confluence is often where business-critical documentation starts, but it is rarely where modern documentation workflows should end.

Teams that want Docs-as-Code usually need more than a one-time export. They need content that can be versioned, reviewed, synchronized, searched, archived, and reused across engineering, support, compliance, and AI workflows. That is where most migrations fail: not at the headline level, but in the details that operators care about once the first export lands on disk.

Why native Confluence exports break Docs-as-Code workflows

The problem is not that Confluence cannot export content. The problem is that default export paths do not produce a durable, automation-friendly Markdown estate.

Common failure modes look like this:

• tables flatten badly or become hard to review in Git
• code blocks lose clean language-aware formatting
• internal page links still point back to Confluence instead of the local documentation tree
• hierarchy is lost, so a space no longer behaves like a navigable docs estate
• downstream search, static publishing, and RAG ingestion inherit noisy or proprietary output

Docs-as-Code is not just a file format choice. It is an operating model. That means the export has to support reviewable diffs, predictable paths, automation, and repeated execution.

Start with the right migration scope

Before choosing a command, decide whether the job is page-precise or estate-wide.

Use acp2md when one page is the real unit of work

Use acp2md when the migration task starts from a single page ID, title, or URL and you need exact control.

That makes it a good fit for:

• high-value compliance pages
• pilot migrations for one document
• troubleshooting formatting before a wider rollout
• building a plain Markdown artifact for legal retention or AI ingestion

Use acs2md when the target is a full documentation estate

Use acs2md when the requirement is to move a whole Confluence space into portable Markdown while preserving hierarchy, rewriting internal links, and supporting repeatable refreshes.

That makes it the right tool for:

• large documentation migrations
• continuity copies
• governed backup workflows
• CI and scheduled sync pipelines
• Git-based documentation estates that must stay current over time

What formatting teams actually need to preserve

The real question is not whether Markdown is simpler than Confluence. The real question is whether the conversion preserves the semantics that matter once content leaves Confluence.

For a serious Docs-as-Code workflow, that usually means keeping:

• headings with a usable document outline
• code blocks in fenced Markdown
• lists and nested structure
• blockquotes and panels in readable form
• tables that are still reviewable in Git
• images and referenced media
• enough metadata to support static site generators or internal pipelines

The ac2md tooling is built around Atlassian Document Format rather than around a superficial copy-and-paste transformation. That matters because the source document model carries structure that a downstream Markdown workflow can preserve much more reliably.

A practical migration workflow that does not collapse at step two

The safest migration path is not export first and clean up later. It is discover first, validate the workstation, confirm the scope, and then export.

1. Validate the environment

Both acp2md and acs2md document an operator-first flow built around doctor, configuration, and license validation before the first real export.

acp2md doctor
acs2md doctor

This catches missing credentials, license issues, and connectivity problems before a migration job is launched against real Confluence content.

2. Confirm the exact scope

For page work, confirm the exact page first.

acp2md page get by-id 2973106197
acp2md page count marks by-url "https://company.atlassian.net/wiki/spaces/DEVOPS/pages/2973106197"

For space work, inventory the space before conversion.

acs2md space pages by-key DOCS
acs2md space convert by-key DOCS --output-dir ./site-content --sync

That sequence matters. It keeps migration planning grounded in the real page tree instead of assumptions about what is in the space.

3. Export to portable Markdown, not to a dead-end artifact

When the goal is Docs-as-Code, output should land in a directory structure that can live in Git, be published by a static site, or feed internal processing.

For page-level export:

acp2md page convert by-id 2973106197 --output ./docs/architecture/target-page.md

For space-scale export:

acs2md space convert by-key DOCS --output-dir ./docs --rewrite-links --sync

At that point the migration is no longer theoretical. You have customer-controlled Markdown on disk.

Where formatting preservation becomes operationally important

Formatting is not just visual polish. It directly affects three downstream systems:

Git review

If headings, tables, and blocks are unstable, diffs become noisy and reviewers stop trusting the export.

Static publishing

If links are not rewritten and hierarchy is lost, the exported tree does not behave like a documentation site. It behaves like a pile of files.

AI and RAG pipelines

If the export strips too much structure, chunks become harder to interpret. If the export preserves the right semantic structure, Markdown becomes far more useful for retrieval and grounded generation.

This is why Climakers positions these tools as migration, continuity, and AI-ready Markdown tooling rather than as simple exporters.

How link rewriting and metadata front matter help

Two features matter immediately once content lands in a Docs-as-Code repository.

Internal link rewriting

For a full-space migration, rewritten internal links are the difference between a self-contained docs estate and an export that still depends on Confluence URLs.

Front matter

Metadata front matter helps downstream systems keep useful context such as author, dates, status, IDs, and other operational attributes.

That becomes useful for:

• static site generation
• audit and retention workflows
• content indexing
• migration validation
• internal automation

Confluence Cloud scope matters

The active acp2md and acs2md tools target Confluence Cloud. They do not support Confluence Server or Data Center.

That boundary matters because migration planning gets worse when teams assume a tool covers more deployment models than it actually does. Clean product boundaries are part of a migration-safe workflow.

Why Docs-as-Code is also a compliance posture

A migration from Confluence to Markdown is not just a tooling decision. It is also a documented-information control decision under ISO 9001, ISO 27001, ISO 27017, NIS 2, and SOC 2. The same artifact that makes Docs-as-Code work — a customer-controlled Markdown estate in Git — is the artifact that turns each of these frameworks from a checklist into something you can actually evidence.

• ISO 9001:2015 clause 7.5 asks for control over documented information: creation, update, distribution, retrieval, and obsolescence. A Git repository encodes those operations as commits, pull requests, branches, and tags. There is no separate “evidence system” to maintain.
• ISO/IEC 27001:2022 treats documented operating procedures (A.5.31) and protection of records (A.5.33) as Annex A controls. When the procedure is a Markdown file in version control, you can produce the entire change history, the approver, and the supersession date with one git log.
• ISO/IEC 27017:2015 extends 27001 into cloud territory. Storing the authoritative copy of cloud-customer documentation outside the cloud provider’s portal is exactly the kind of customer-side control the standard expects.
• NIS 2 requires documented policies on cybersecurity risk management, incident handling, and business continuity. A Markdown estate is the most direct way to satisfy the documentation duty without locking yourself into a single SaaS platform whose availability is itself a risk.
• SOC 2 Common Criteria CC2.2 and CC2.3 require entities to communicate documented policies. Customer-controlled Markdown lets you publish the same source-of-truth content to internal portals, external trust pages, and auditors without divergence.

Treating Docs-as-Code as a compliance posture also changes how you justify the migration internally. You are not “moving away from Confluence”. You are bringing the documented information that runs your business under controls your auditors already expect.

A sensible migration checklist for Docs-as-Code teams

If you want the shortest path to a controlled migration, use this checklist:

1. Decide whether the job is page-level or space-level.
2. Configure credentials and validate with doctor.
3. Inspect the target page or space before conversion.
4. Export Markdown into a Git-friendly output path.
5. Confirm hierarchy, links, code blocks, tables, and media behavior.
6. Run the export again using --sync or incremental workflows when the goal is continuity, not just one-time migration.
7. Publish or process the Markdown in your static site, portal, or AI pipeline.

Final take

The best Confluence-to-Docs-as-Code migration is not the one that produces the most files fastest. It is the one that gives your team control, portability, and a repeatable workflow without losing the formatting details that make documentation usable.

If the problem starts with one page, use acp2md. If it starts with a whole documentation estate, use acs2md.

In both cases, the goal is the same: move from knowledge trapped in a proprietary workspace to customer-controlled Markdown that can survive migration, continuity, publishing, AI reuse, and the next ISO 27001 surveillance audit. When you are ready, start with acp2md for a single page or pick an acs2md plan for the whole space.