---
title: "Migrate from Confluence to GitBook | ClonePartner"
description: "There is no one-click migration path from Confluence to GitBook that preserves macros, attachments, and internal links. GitBook's built-in importer caps at 20 p"
source: Confluence
target: GitBook
canonical: "https://clonepartner.com/migrate/confluence-to-gitbook/"
---

# Confluence → GitBook migration

Seamless Confluence to GitBook migration — all records moved with accuracy and care.

## Why teams migrate from Confluence to GitBook

There is no one-click migration path from Confluence to GitBook that preserves macros, attachments, and internal links. GitBook's built-in importer **caps at 20 pages** and scrapes rendered output, losing macro structure entirely.



Confluence stores content in a **proprietary XHTML-based storage format** with custom XML elements for macros. GitBook is a **Markdown-first, Git-backed** documentation platform with no macro concept.



Real migrations require XML-to-Markdown conversion, a **SUMMARY.md** for hierarchy mapping, attachment re-hosting through Git, and a deliberate redirect plan for old Confluence URLs.

## Key migration challenges

- **Storage Format Conversion** — Confluence's proprietary XML with ac:structured-macro elements must be parsed and converted to clean Markdown with custom rules per macro type.
- **Macro Translation** — Each Confluence macro requires a dedicated conversion rule. Layout macros, Jira embeds, and page includes have no direct GitBook equivalent.
- **Native Import Cap** — GitBook's built-in import panel is limited to 20 pages and 20 files per import, making it unusable for real migrations.
- **Attachment Re-hosting** — Attachments must be downloaded from Confluence, placed in a Git repository or external storage, and re-linked in Markdown files.
- **Deep Nesting Limits** — Confluence allows unlimited page nesting. GitBook recommends three levels or fewer for usable sidebar navigation.

## Entity mappings

- **Spaces** (Confluence) → **Space** (GitBook)
- **Pages** (Confluence) → **Page** (GitBook)
- **Blog Posts** (Confluence) → **Page** (GitBook)
- **Attachments** (Confluence) → **File/Asset** (GitBook)
- **Ancestors (Page Hierarchy)** (Confluence) → **Page** (GitBook)
- **Space Permissions** (Confluence) → **Space Permission** (GitBook)
- **Groups** (Confluence) → **Team** (GitBook)
- **Labels** (Confluence) → **Not directly available (partial workaround possible)** (GitBook)
- **Comments (Footer)** (Confluence) → **NotAvailable (workaround: append to page body or use GitBook API page descriptions)** (GitBook)
- **Content Restrictions** (Confluence) → **Space Permission** (GitBook)
- **Space Categories** (Confluence) → **Collection** (GitBook)
- **Tasks** (Confluence) → **Workaround — Embedded content within Pages (checklists/task lists in Markdown) or external integration** (GitBook)

## What breaks during migration

- **Layout Macros (columns)** [Breaks] — No Markdown equivalent — content must be linearized
- **Jira Issue Macros** [Breaks] — No GitBook equivalent — become plain text links
- **Internal Links** [Breaks] — All Confluence URLs break without a pageId-to-path mapping
- **Inline Comments** [Breaks] — Stored separately from page body — not included in any export
- **Page Version History** [Breaks] — Does not migrate — Git commit history starts fresh
- **Nested Tables** [Breaks] — Markdown does not support nested tables — must restructure
- **Draw.io / Gliffy Diagrams** [Workaround] — Must be exported as PNG/SVG images and re-embedded
- **Page Body Content** [Direct] — Standard text, headings, lists, and simple tables convert cleanly
- **Code Blocks** [Direct] — Direct conversion to Markdown fenced code blocks
- **Info/Warning Panels** [Direct] — Map to GitBook hint blocks with type matching

## What we migrate

### Migration Filter

- **Time Range** — Migrate articles created or updated within a specific period
- **Language & Locale** — Migrate specific language versions or translations only
- **Category Selection** — Select specific sections, folders, or categories to migrate
- **Publication Status** — Filter by published, draft, archived, or internal-only articles

### Data Types

- **Tags & Metadata** — SEO settings, search labels, author attribution, and article tags
- **Articles & Content** — Core help articles including HTML formatting and inline images
- **Media & Attachments** — All downloadable files, PDFs, and media assets embedded in articles
- **Categories & Hierarchy** — Full folder structure with sections, sub-sections, and parent categories

## Complete technical guide

For a deep-dive into the technical process, data mapping, and step-by-step migration workflow, read our full guide: [Confluence to GitBook Migration: The CTO's Technical Guide](https://clonepartner.com/blog/confluence-to-gitbook-migration-the-ctos-technical-guide/).

## Frequently asked questions

### Can I import Confluence pages directly into GitBook?

Yes, but with hard limits. GitBook's built-in import panel supports Confluence by URL or file upload, but it caps at 20 pages and 20 files per import. It scrapes the rendered page, not the storage format, so macro structure is lost. For larger migrations, GitBook recommends using Git Sync with a repository of pre-converted Markdown files.

### What happens to Confluence macros when migrating to GitBook?

Confluence macros use a proprietary XML format (ac:structured-macro) that has no direct Markdown equivalent. Simple macros like code blocks and info panels map to GitBook blocks. Complex macros like Jira issue embeds, Draw.io diagrams, and multi-column layouts either require manual conversion, approximation as images or plain text, or are lost entirely. Each macro type needs a custom conversion rule.

### What are the GitBook API rate limits for migration scripts?

GitBook's API returns HTTP 429 when rate limits are exceeded, with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Migration scripts must implement exponential backoff. Sustained rate limit violations risk token revocation.

### Can I keep Confluence and GitBook in sync during migration?

Bidirectional sync between Confluence and GitBook is not practical. Confluence's XML storage format and GitBook's Markdown are fundamentally incompatible for clean round-trips. The reliable approach is a one-way cutover: extract from Confluence, convert, import into GitBook, run a final delta sync, then decommission the Confluence space.

### How long does a Confluence to GitBook migration take?

A small space (under 50 pages, minimal macros) can be migrated in a day using the Git Sync pipeline. Enterprise instances with 500+ pages, heavy macro usage, and complex hierarchies typically take 1–2 weeks including conversion script development, testing, and validation — or 2–5 days with a managed migration service.

## Get a fixed-price quote

[Talk to an engineer](https://cal.com/clonepartner/meet?duration=30&utm_source=xtoy&utm_medium=button&utm_campaign=demo_bookings&utm_content=cta_click&utm_term=demo_button_click) about your Confluence → GitBook migration.