Zendesk Guide to Confluence Migration: The CTO's Technical Guide

Migrating a knowledge base from Zendesk Guide to Confluence is not a content copy job. Zendesk Guide stores articles in a structured hierarchy with HTML bodies, inline images hosted on Zendesk's CDN, and metadata tied to the support ecosystem. Confluence stores content in a proprietary XHTML-based storage format with custom XML elements for macros, layouts, and structured data. Every migration approach available today — CSV export, API scripts, middleware — silently drops at least one of those dimensions unless you engineer around it.

If your goal is only to surface Confluence content inside Zendesk agent search, Zendesk's Knowledge Connector to Confluence may remove the need for a migration entirely — but it syncs Confluence into Zendesk, not the other way around. If you need Zendesk content in Confluence, you need a migration.

This guide covers the architectural differences, API constraints on both sides, data mapping strategies, and the specific edge cases that derail teams mid-migration. If you need to export your Zendesk content first, start with How to Export Data from Zendesk Guide: Methods, Limits & Formats. For the Confluence import side, see How to Import Data into Confluence: Methods, API Limits & Mapping.

Zendesk Guide vs. Confluence: Core Architecture Differences

Zendesk Guide is a structured knowledge base tightly coupled to the Zendesk Support ecosystem. Content follows a rigid hierarchy: Categories contain Sections, and Sections contain Articles. On Enterprise plans, sections can nest multiple levels deep, but articles can only live inside sections — never directly under categories. (support.zendesk.com)

Confluence is a wiki-based collaboration platform with a fundamentally different content model. Content is organized into Spaces, and each Space contains Pages that can nest infinitely as child pages. There's no enforced hierarchy pattern — a Space can hold flat pages, deeply nested trees, or both.

The differences that matter for migration:

Why Companies Make This Move

The most common drivers we see across migrations:

• Atlassian consolidation. Teams already on Jira and Confluence want all documentation in one ecosystem instead of paying for a separate Zendesk Guide license.
• Internal knowledge centralization. Zendesk Guide is designed for customer-facing help centers. Teams migrating internal docs to Confluence gain wiki features like page trees, cross-linking, and the Confluence editor.
• Cost reduction. Zendesk Suite licensing is per-agent. Moving the KB to a Confluence plan that's already paid for reduces the Zendesk footprint.
• No native reverse connector. Zendesk's Knowledge Connector syncs Confluence content into Zendesk for agent search — not the other way around. If you want Zendesk content in Confluence, you need a migration. (support.zendesk.com)

Migration Approaches: API vs. CSV vs. Middleware

There are five realistic paths for moving content from Zendesk Guide to Confluence. Each has hard trade-offs.

1. Native CSV Export + Manual Import

How it works: There is no true native Zendesk Guide article export. Teams approximate this by exporting metadata via CSV from Admin Center, then manually recreating content in Confluence. Confluence only bulk-imports Word, Google Docs, or OneDrive files — web content is imported page by page. (support.zendesk.com)

When to use it: Fewer than 50 articles with simple formatting. No inline images. No automation requirements.

Limitations: Zendesk's native CSV export does not include article HTML bodies, inline images, or attachments. You get metadata — title, URL, status — but not the actual content. This makes CSV export essentially useless for a content migration. For more on these constraints, see How to Export Data from Zendesk Guide: Methods, Limits & Formats.

Complexity: Low | Fidelity: Very Low | Scalability: Not viable beyond trivial volumes

2. API-Based Migration (Custom Scripts)

How it works: Extract articles via the Zendesk Help Center API (/api/v2/help_center/articles.json), transform HTML to Confluence XHTML storage format, then create pages via the Confluence REST API.

When to use it: You have engineering capacity and need full control over the transformation logic — especially for complex formatting, macro insertion, or conditional page structures.

Pros:

• Full access to article HTML, metadata, labels, and attachments
• Control over hierarchy mapping and XHTML transformation
• Can preserve timestamps, authorship, and labels

Cons:

• HTML → Confluence XHTML storage format conversion is non-trivial (custom ac: namespace elements, macro wrappers)
• Must handle inline image re-hosting (download from Zendesk CDN, upload as Confluence attachments, rewrite src URLs)
• Rate limits on both ends constrain throughput
• Zendesk documents formatting drift when teams mix Help Center UI edits with API updates (developer.zendesk.com)

Complexity: High | Fidelity: High (if built correctly) | Scalability: Enterprise-grade with proper rate limit handling

3. Third-Party Migration Tools

How it works: Tools like Help Desk Migration offer pre-built connectors between Zendesk and Confluence. You configure field mappings in a GUI and run the migration. Zendesk itself points customers to partner apps for content migrations.

When to use it: Mid-volume migrations where you want to avoid custom code but accept some formatting compromises.

Limitations: Most tools map flat content (title + body) and don't handle Confluence's storage format nuances. Tables inside articles may render incorrectly. Macros won't be inserted. Image re-hosting varies by tool.

Complexity: Medium | Fidelity: Medium | Scalability: Depends on tool pricing and API allocation

4. Custom ETL Pipeline

How it works: A purpose-built Extract-Transform-Load pipeline that pulls from Zendesk, transforms content through a processing layer (HTML parsing, image handling, XHTML generation), and loads into Confluence. Uses the incremental articles endpoint for delta sync before cutover.

When to use it: Large-scale migrations (500+ articles) where you need repeatable runs, dry-run validation, error logging, and rollback capability.

Pros:

• Most reliable for high-fidelity, large-volume migrations
• Supports incremental runs and delta syncs
• Full audit trail and error handling
• Idempotent and testable

Cons:

• Significant upfront engineering investment
• Requires deep knowledge of both APIs and Confluence's storage format

Complexity: High | Fidelity: Highest | Scalability: Best option for enterprise volumes

5. Middleware / Integration Platforms (Zapier, Make)

How it works: Use an iPaaS platform to trigger on Zendesk events and create Confluence pages. Typically configured as a workflow: "When article updated in Zendesk → Create/update page in Confluence."

When to use it: Ongoing sync scenarios where you want Confluence to mirror Zendesk Guide content continuously. Not suitable for one-time bulk migrations.

Limitations: These platforms pass content as plain text or basic HTML — they don't generate Confluence storage format XHTML. You'll get pages with broken formatting, no macros, and no attachment handling. Zapier's Confluence Cloud integration exposes page triggers and a Create Page action, but polling on the Free plan is limited to every 15 minutes. (zapier.com)

Complexity: Low | Fidelity: Low | Scalability: Good for lightweight sync, poor for bulk migration

Approach Comparison

Scenario Recommendations

• Small team, <100 articles, low engineering bandwidth: Third-party tool with manual formatting cleanup.
• Enterprise, 500+ articles, dedicated dev team: Custom ETL pipeline or API scripts with full XHTML transformation.
• Ongoing sync requirement: Consider whether you actually need migration or if Zendesk's Knowledge Connector (Confluence → Zendesk direction) meets your needs. If you need the reverse direction, a middleware sync may work for thin deltas only.
• Search coexistence, not repository consolidation: Evaluate the Knowledge Connector before migrating anything.
• Need it done in days, not weeks: Managed migration service.

When a Managed Migration Service Makes Sense

Building a Zendesk Guide to Confluence migration in-house sounds straightforward until you hit the transformation layer. The real engineering cost isn't the API calls — it's converting Zendesk's HTML into valid Confluence XHTML storage format.

Confluence's storage format is technically XML, not standard HTML. Simple paragraphs work (<p>text</p>), but tables, code blocks, info panels, and layouts all require Confluence-specific XML elements (<ac:structured-macro>, <ac:rich-text-body>, <ri:page>). A migration script that pushes raw HTML into Confluence will produce pages that render unpredictably or break the editor. Atlassian's content-body conversion API converts between Confluence representations like storage and atlas_doc_format — it does not turn arbitrary Zendesk HTML into valid Confluence storage for you. (developer.atlassian.com)

Hidden costs of DIY migration:

• XHTML transformation engineering. Expect 30–50% of total development time spent on HTML → storage format conversion, especially for articles with tables, embedded media, or custom CSS.
• Image re-hosting. Every inline image needs to be downloaded from Zendesk's CDN, uploaded as a Confluence attachment, and the <img src> rewritten to a Confluence attachment reference. This is per-article, per-image.
• Rate limit management. You're constrained on both sides — Zendesk and Confluence — and both have different rate limiting models.
• Content block flattening. Zendesk flattens reusable content blocks to inline text in API responses and does not support content-block placeholders on update. If your articles use content blocks, expect formatting drift. (developer.zendesk.com)
• Validation and cleanup. Automated migrations always produce some percentage of pages that need manual review. The question is whether that's 2% or 20%.

Do not build this in-house just because the raw object count looks manageable. Build in-house only if the migration itself is important enough to justify ETL code, test fixtures, retry logic, operator runbooks, and a full QA cycle.

ClonePartner handles these migrations by connecting directly to the Zendesk Help Center API, preserving article HTML and attachments, and transforming content into valid Confluence storage format. We automatically map Zendesk Guide's hierarchy into Confluence's Space and Child Page structure, handle inline image re-hosting, and manage rate limits on both platforms. For teams that also need to migrate associated Zendesk Support data (organizations, users, ticket references) into Confluence as structured page content, we map those relationships using Confluence's Page Properties macro.

Pre-Migration Planning & Data Audit

Before writing a single line of code or configuring a tool:

Content Audit Checklist

• Total article count across all categories and sections
• Number of articles with inline images (these require re-hosting)
• Articles with embedded videos or iframes
• Draft vs. published vs. archived article counts
• Multi-language articles and translation relationships
• Articles using custom HTML/CSS (common in Zendesk themes)
• Articles using content blocks (these flatten through the API)
• Attachment count and total file size
• Labels in use and their mapping to Confluence labels

Associated Data Inventory

If you're consolidating beyond the KB:

• Organizations and Users referenced in article permissions
• Ticket references or links embedded in articles
• Community posts linked to KB articles
• Custom objects or metadata tied to the Zendesk ecosystem
• Zendesk macros that link to specific KB articles

Define Scope and Strategy

What to migrate:

• Published articles (always)
• Draft articles (only if actively being worked on)
• Archived articles (usually skip — archive locally as HTML backup instead)

Migration strategy:

• Big bang: Migrate everything in one window. Works for smaller, low-risk internal KBs. Requires a cutover weekend. You extract the data, transform it, load it into Confluence, update your DNS/redirects, and decommission Zendesk Guide simultaneously to avoid split-brain documentation.
• Phased: Migrate by category. Reduces risk and allows parallel validation.
• Incremental: Migrate in batches, validate each batch, then proceed. Best for large KBs or public content that needs a short parallel authoring window before final switchover.

Data Model & Object Mapping: KB Hierarchy and Structured Data

This is where most migrations go wrong. The hierarchy mismatch between Zendesk Guide and Confluence requires deliberate mapping decisions.

KB Hierarchy Mapping

The key decision: do you create one Confluence Space per Zendesk Category, or one Space for the entire Help Center with Categories as top-level pages?

For most migrations, one Space with Categories as top-level parent pages is the right call. It keeps the content searchable within a single Space and avoids Space proliferation, which is an admin burden in Confluence. If you have multiple Zendesk brands, create one Space per brand.

Many older migration runbooks assume Zendesk is strictly Category → Section → Article (three levels). On Enterprise plans, sections can nest multiple levels deep. Inspect the live parent chain in your Zendesk instance before you design your mapping. (support.zendesk.com)

Mapping CRM-Adjacent Data to Confluence

If you're migrating associated Zendesk Support or Sell data alongside the KB, Confluence has no native CRM objects. You'll need to represent structured data using Confluence's Page Properties macro.

The Page Properties macro stores metadata as a two-column table inside an <ac:structured-macro ac:name="details"> block. Combined with the Page Properties Report macro on a parent page, this creates a queryable index — the closest Confluence gets to a structured data view.

Migration Architecture & API Constraints

The data flow follows a standard ETL pattern: Extract from Zendesk → Transform HTML to Confluence XHTML → Load into Confluence → Validate.

Zendesk Help Center API: Extraction

The Help Center API provides dedicated endpoints for each content type:

• GET /api/v2/help_center/categories.json — List all categories
• GET /api/v2/help_center/sections.json — List all sections
• GET /api/v2/help_center/articles.json — List all articles (returns body as HTML)
• GET /api/v2/help_center/articles/{id}/attachments.json — Article attachments

Rate limits by plan:

Help Center API limits are counted separately from the Support API. The incremental articles endpoint (/api/v2/help_center/incremental/articles.json) returns up to 1,000 articles per page, making it the most efficient bulk extraction method. Note that this endpoint has a stricter rate limit of 10 requests per minute.

Use cursor-based pagination (page [size]=100) instead of offset pagination for standard list endpoints. Offset pagination is capped at 100 pages and can fail beyond 10,000 records. Zendesk recommends cursor pagination for all new integrations.

The article model exposes fields such as body, html_url, source_locale, outdated_locales, and visibility controls — all of which you can preserve as metadata in Confluence. (developer.zendesk.com)

Confluence REST API: Loading

Confluence Cloud's REST API uses a points-based rate limiting model that went into phased enforcement on March 2, 2026. Each API call consumes points based on the operation's complexity — a page creation request costs more than a simple read.

Key constraints:

• Burst limits are evaluated over short time windows (seconds) to prevent traffic spikes.
• Quota limits are evaluated hourly.
• Both are enforced independently — you can hit burst limits even if you're within your hourly quota.
• API token-based traffic (typical for migration scripts) continues to use existing burst rate limits and is not affected by the new points-based model for apps.

Page creation requires content in Confluence's XHTML-based storage format. The body must be submitted as storage representation:

{
  "type": "page",
  "title": "Getting Started with Billing",
  "space": {"key": "KB"},
  "ancestors": [{"id": "123456"}],
  "body": {
    "storage": {
      "value": "<p>Your transformed XHTML content here</p>",
      "representation": "storage"
    }
  }
}

Confluence uses optimistic locking for updates — you must include the current version number incremented by one. If another edit occurs between your read and write, the update fails with a version conflict.

Attachment upload still uses the v1 content attachment endpoint with multipart/form-data and the X-Atlassian-Token: nocheck header. For a deeper dive into these constraints, see How to Import Data into Confluence: Methods, API Limits & Mapping.

Step-by-Step Migration Process

Step 1: Extract from Zendesk Guide

Pull the full hierarchy and content:

import requests
import time
import os
 
ZENDESK_SUBDOMAIN = "https://yourcompany.zendesk.com"
AUTH = ("email@company.com/token", "YOUR_API_TOKEN")
 
def fetch_all_paginated(endpoint):
    results = []
    url = f"{ZENDESK_SUBDOMAIN}{endpoint}"
    while url:
        response = requests.get(url, auth=AUTH)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue
        response.raise_for_status()
        data = response.json()
        key = list(data.keys())[0]  # 'articles', 'sections', etc.
        results.extend(data[key])
        url = data.get("next_page")
    return results
 
categories = fetch_all_paginated("/api/v2/help_center/categories.json")
sections = fetch_all_paginated("/api/v2/help_center/sections.json")
articles = fetch_all_paginated("/api/v2/help_center/articles.json")

For each article, download inline images and attachments:

def download_attachments(article_id, output_dir):
    attachments = fetch_all_paginated(
        f"/api/v2/help_center/articles/{article_id}/attachments.json"
    )
    for att in attachments:
        img_data = requests.get(att["content_url"]).content
        filepath = os.path.join(output_dir, att["file_name"])
        with open(filepath, "wb") as f:
            f.write(img_data)
    return attachments

Use the brand-specific subdomain if you have multiple brands. For the final cutover, use the incremental articles endpoint to collect deltas since the last full export.

Step 2: Transform HTML to Confluence Storage Format

This is the hardest step. Zendesk article bodies are HTML. Confluence expects XHTML with custom namespaces.

Key transformations:

• Self-closing tags: <br> → <br />, <img ...> → <img ... />
• Image sources: Replace Zendesk CDN URLs with Confluence attachment macros: <ac:image><ri:attachment ri:filename="image.png" /></ac:image>
• Code blocks: <pre><code> → <ac:structured-macro ac:name="code"><ac:plain-text-body><! [CDATA [...]]></ac:plain-text-body></ac:structured-macro>
• Info/warning callouts: Map Zendesk's styled divs to Confluence info/warning macros
• Tables: Standard HTML tables work in Confluence storage format, but verify <th> handling
• Internal links: Rewrite Zendesk article links to Confluence page links using <ac:link><ri:page ri:content-title="Page Title" /></ac:link>

If you are mapping CRM data, dynamically generate the XML for the Page Properties macro during this step. For more on transforming external HTML for Atlassian, see SharePoint to Confluence Migration: The Complete Technical Guide.

Step 3: Create Pages in Confluence

Create the hierarchy in dependency order — Spaces first, then parent pages, then leaf pages:

import requests
 
CONFLUENCE_BASE = "https://yourcompany.atlassian.net/wiki/rest/api"
CONF_AUTH = ("email@company.com", "CONFLUENCE_API_TOKEN")
 
def create_confluence_page(title, body_xhtml, space_key, parent_id=None):
    payload = {
        "type": "page",
        "title": title,
        "space": {"key": space_key},
        "body": {
            "storage": {
                "value": body_xhtml,
                "representation": "storage"
            }
        }
    }
    if parent_id:
        payload["ancestors"] = [{"id": parent_id}]
    
    response = requests.post(
        f"{CONFLUENCE_BASE}/content",
        json=payload,
        auth=CONF_AUTH,
        headers={"Content-Type": "application/json"}
    )
    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 30))
        time.sleep(retry_after)
        return create_confluence_page(title, body_xhtml, space_key, parent_id)
    response.raise_for_status()
    return response.json()["id"]

Step 4: Upload Attachments and Rewrite References

After creating each page, upload downloaded images as attachments via the Confluence Attachments API, then update the page body with correct ri:attachment references pointing to the uploaded filenames. The XHTML must reference the new attachment ID, not the old Zendesk CDN URL — if you skip this step, images will 404 when Zendesk is decommissioned.

Step 5: Rebuild Internal Links

After all pages exist, update cross-links. Every Zendesk article-to-article link must be remapped using the source-to-target ID lookup table you built during load. Update parent-child navigation, locale branches, and any reference pages that aggregate child content using the Page Properties Report macro.

Step 6: Validate

Run validation checks after each batch — not just at the end. Compare article counts, spot-check formatting on 10–15% of pages, and verify all images render. See the Validation section below for the full process.

Edge Cases That Break Migrations

Inline images with query parameters. Zendesk CDN URLs often include query strings for resizing. Your download logic needs to strip or handle these, and your filename extraction must account for them.

Multi-language articles. Zendesk Guide stores translations as separate objects linked to the same article ID. Confluence doesn't have native per-page locale settings. Options: create separate pages per language (with a naming convention like "Article Title [FR]"), use the Scroll Translations add-on for Confluence, or maintain separate Spaces per language. Decide before you build — this affects your entire page structure.

Articles with embedded iframes. Zendesk allows iframes for embedded videos (YouTube, Vimeo). Confluence Cloud strips iframes for security. Convert these to Confluence's Widget Connector macro or accept the loss.

Internal cross-links between articles. Zendesk articles link to each other via full URLs (/hc/en-us/articles/123456). Every internal link must be remapped to the corresponding Confluence page URL or <ac:link> element. Build a lookup table of old Zendesk article IDs → new Confluence page IDs during migration. If you fail to do this, your wiki will be full of dead links.

Custom CSS in articles. Zendesk Guide themes can inject custom CSS that affects article rendering. This CSS doesn't transfer to Confluence. Articles that relied on theme CSS for layout will look broken and require manual cleanup.

Duplicate page titles. Confluence enforces unique page titles within a Space. If two Zendesk articles have the same title (common across sections), you'll hit conflicts. Append the section name or a suffix during transformation.

Content blocks. Zendesk flattens reusable content blocks to inline text in API responses and does not support content-block placeholders on update. The relationship between shared blocks will not survive the migration — each article gets a frozen copy of the block content. (developer.zendesk.com)

Mixed editor and API workflows. If articles were edited both in the Zendesk UI and through the API, repeated GET/PUT cycles can reintroduce legacy HTML or change rendering. Extract carefully and normalize during transformation. (developer.zendesk.com)

For more on Confluence-specific failure modes during cloud migrations, see Confluence Cloud Migration Assistant (CCMA) Failures: Recovery Guide.

Limitations & Constraints to Accept

• No true custom objects in Confluence. Zendesk's custom objects and fields don't have a Confluence equivalent. Page Properties is the closest workaround, but it's metadata on a page, not a queryable database.
• Storage format conversion is lossy for complex HTML. Articles with complex nested <div> layouts, custom class names, or CSS-dependent formatting will require manual cleanup.
• No native Zendesk → Confluence connector. Zendesk's Knowledge Connector syncs Confluence content into Zendesk. There is no native reverse connector. This migration is always a custom or third-party job.
• Permission mapping is not 1:1. Zendesk Guide permissions (e.g., "Visible to Signed-in Users") do not map directly to Confluence Space permissions. You must manually configure Confluence user groups post-migration.
• Loss of ticket deflection. Zendesk Guide natively integrates with Zendesk Support to deflect tickets. Confluence does not do this unless integrated with Jira Service Management.
• Timestamps cannot be set via API. Confluence does not allow setting page creation or modification dates through the API. Store them as metadata in a Page Properties macro if you need to preserve them.
• Attachment size limits. Confluence Cloud has a default attachment size limit of 250 MB per file. Zendesk article attachments can be up to 20 MB (developer.zendesk.com), so this is unlikely to be an issue for KB content.

Validation & Testing

Record Count Validation

After migration, compare:

• Total articles in Zendesk vs. total pages created in Confluence
• Articles per section in Zendesk vs. child pages per parent page in Confluence
• Total attachments downloaded vs. total attachments uploaded
• Translation coverage if multilingual

Field-Level Spot Checks

Sample 10–15% of migrated pages and verify:

• Article title matches page title
• Body content renders correctly (tables, code blocks, images)
• All inline images display (not broken attachment references or lingering zendesk.com URLs)
• Labels transferred correctly
• Internal links point to valid Confluence pages

UAT Process

1. Migrate to a staging Space first — never directly to production.
2. Have content owners review their sections for formatting accuracy.
3. Test search: can users find migrated articles via Confluence search?
4. Verify permissions: are restricted articles still restricted in Confluence?

Rollback Plan

Confluence makes rollback straightforward: delete the migrated Space. Your Zendesk Guide data remains untouched throughout the migration — this is a read-only extraction. Always keep a full HTML backup of all articles before cutover.

Post-Migration Tasks

• Set up redirects if the Help Center was public. If your Zendesk Guide served external traffic, implement 301 redirects from old Zendesk URLs to new Confluence page URLs to preserve SEO equity.
• Rebuild automations. Zendesk Guide triggers (e.g., "article published → notify team") don't carry over. Recreate them using Automation for Confluence or Jira automation rules. If you used Zendesk macros to insert KB links into tickets, update those macros with the new Confluence URLs.
• Update internal links and bookmarks. Any dashboards, wiki pages, Slack bookmarks, or documentation that links to Zendesk Guide URLs needs to be updated.
• User training. Confluence's editor and page tree navigation differ significantly from Zendesk Guide's admin interface. Plan a brief onboarding session for content authors.
• Monitor for data inconsistencies. Run the validation checks weekly for the first month. Late-discovered issues are common with image references and internal links.

Sample Data Mapping Table

Best Practices

• Back up everything before migration. Export all Zendesk articles as HTML files locally. This is your recovery baseline.
• Run test migrations first. Migrate a single section to a test Confluence Space. Validate formatting, images, and links before scaling up.
• Validate incrementally. Don't wait until the full migration completes to check results. Validate after each category or batch.
• Use the incremental articles endpoint for bulk extraction. It returns up to 1,000 articles per page and is the most efficient way to pull large KBs.
• Handle rate limits proactively. Read the Retry-After header on every 429 response. Build adaptive throttling with jitter, not fixed delays. Both Zendesk and Atlassian document this pattern. (developer.atlassian.com)
• Log everything. Maintain a mapping of every Zendesk_Article_ID to its new Confluence_Page_ID, with body checksums, attachment counts, retry counts, and last error. This is essential for link rewrites, SEO redirects, and audit.
• Generate a redirect map. For every migrated article, record the old Zendesk URL and new Confluence URL. This map is critical for SEO redirects and for updating internal links across your systems.
• Never test in production. Always use a Confluence sandbox or staging Space.
• Batch your API calls. Send requests in controlled batches to respect Atlassian's points-based rate limits. Log every unit of work with source ID, target ID, and status.

For the broader context on knowledge base migration planning — including URL preservation and SEO considerations — see The Ultimate Knowledge Base Migration Checklist: A Zero-Downtime Plan.

Make the Cutover Boring

Most Zendesk Guide to Confluence migrations fail for one of three reasons: teams choose a lossy export path, underestimate HTML-to-XHTML transformation, or treat Confluence like a drop-in clone of Zendesk Guide. The safer pattern is consistent: audit the real hierarchy (including nested subsections), extract through APIs, transform deliberately, load in dependency order, and validate at both record and field level.

If adjacent CRM or support objects are in scope, decide early whether Confluence serves as an archive, a search surface, or a platform you're willing to extend with Forge. Those are different architectures, and picking the wrong one is where projects quietly go sideways.