Zendesk Guide to Confluence migration requires HTML-to-XHTML storage format conversion, inline image re-hosting, and hierarchy remapping — CSV export won't cut it. Use the API.
There is no native migration path from Zendesk Guide to Confluence; Zendesk's Knowledge Connector only syncs Confluence content into Zendesk, not the reverse. The fundamental challenge is that Zendesk Guide stores articles as rendered HTML with images on Zendesk's CDN, while Confluence requires a proprietary XHTML-based storage format using custom ac: XML namespace elements for macros, layouts, and embedded media. Successfully migrating content requires extracting articles via the Zendesk Help Center API, transforming HTML into valid Confluence storage format XHTML, re-hosting all inline images as Confluence attachments, and remapping the Category → Section → Article hierarchy to Confluence's Space → Page → Child Page model.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
Don't migrate archived or obsolete articles
Every unnecessary article increases transformation time, validation effort, and the chance of errors. Audit first, migrate second.
Freeze information architecture changes before the final delta run
New sections, re-parented content, or late permission changes create avoidable mapping drift.
Confluence is a wiki, not a relational database or a CRM
If your migration requires preserving multi-level relationships (Organization → Contact → Opportunity) or your sales team actively updates hundreds of records daily, keep that data in a dedicated CRM. Confluence is best for static or slow-changing documentation. If you truly need object semantics and workflow in Atlassian, consider a Forge app instead of forcing Confluence pages to impersonate CRM records.
Do not push raw HTML into Confluence's storage format field
It may render initially but will corrupt the page when edited, breaking the Confluence editor. All content must be valid XHTML with proper Confluence namespace elements.
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Decide what content deserves to move before you plan how to move it.
Objective A content inventory with a keep/rewrite/retire decision on every article and an agreed URL strategy.
Keep these open
-
Inventory all content in Zendesk Guide
Count articles, categories, attachments, images and embedded media, and pull page views and last-updated dates for each article. Usage data is what makes the next decision defensible rather than political.
Data Profiler Get real record counts instead of estimating from memory -
Make a keep, rewrite or retire call on every article
Most knowledge bases are half stale. Migrating everything imports the staleness and doubles the work; use views and last-updated to triage, and get the owning team to confirm. This usually removes 30-50% of scope.
Migrating stale content is the most common knowledge-base migration mistake — it costs effort and actively degrades the new site.
-
Agree the URL and redirect strategy
Decide the Confluence URL structure and whether you can serve 301 redirects from the old paths. Public help centres carry real search traffic and inbound links; losing it is a measurable commercial impact.
Without 301 redirects from old article URLs you lose accumulated search ranking and every external link and bookmark breaks.
-
Map the information architecture
Document the current category tree and design the target one, checking whether Confluence supports your nesting depth. Deeply nested hierarchies frequently have to be flattened, which changes navigation for everyone.
-
Confirm permissions, audiences and localisation scope
Establish which content is public, internal or restricted, and how Confluence models that. Then confirm how many locales you have and whether translation relationships between articles survive the move.
Zendesk Guide → Confluence specifics
- 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)
- 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.
Don't move on until
- Full content inventory with page views and last-updated dates
- Keep / rewrite / retire decision recorded per article
- URL and redirect strategy agreed with whoever owns SEO
02 Data Audit Audit the markup, the links and the assets — that is where KB migrations break.
Objective A content export with markup, internal links and every embedded asset accounted for.
Keep these open
-
Export content and assess markup fidelity
Export articles in the richest format available and inspect what survived: tables, code blocks, callouts, nested lists, anchors and embedded video. Rich formatting is where fidelity is lost, and it is lost quietly.
HTML-to-Markdown conversion routinely mangles nested lists, tables and code blocks. Inspect the output rather than trusting the converter.
Data Profiler Profile the Zendesk Guide export for nulls, outliers and type drift -
Inventory every internal link and cross-reference
Extract all internal links, anchor links and article cross-references. These break by default: the target URL structure differs, so every internal link needs rewriting as part of the load, not afterwards.
Internal links left pointing at old URLs turn the new knowledge base into a maze of 404s on day one.
-
Inventory images, attachments and embedded media
List every asset with its URL, size and type, and confirm each still resolves. Assets hosted on the old platform's CDN will 404 the moment you decommission it, so they must be rehosted, not referenced.
Images referenced from the source platform's CDN break when the old account closes. Download and rehost every asset.
-
Find and fix broken links and orphans
Crawl for existing broken internal and external links, and find articles no category links to. Fix them before migrating — a migration is a bad time to discover pre-existing rot.
-
Check for PII and internal information in public content
Scan for customer names, internal hostnames, credentials in code samples and screenshots containing real data. Republishing these on a public help centre is a disclosure, and screenshots are the usual culprit.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Normalise metadata
Standardise authors, tags, timestamps to UTC, and locale codes. Author mapping needs a decision for people who have left — attribution to a deleted user usually fails the import.
Don't move on until
- Content exported with markup fidelity assessed
- Every internal link and asset reference inventoried
- Broken links and missing assets fixed or logged
03 Field Mapping Map structure, metadata, permissions and — above all — URLs.
Objective A mapping covering article fields, taxonomy, permissions and a complete old-to-new URL map.
Keep these open
-
Map the article schema
Map title, body, excerpt, author, dates, status, tags, SEO metadata and any custom properties. Confirm which fields Confluence lets you set on import versus which it computes — computed dates are a common surprise.
Schema Mapper Opens pre-loaded with the Zendesk Guide → Confluence field pair -
Map the taxonomy and hierarchy
Map categories, sections and tags to the target structure, resolving any nesting-depth limit explicitly. If you must flatten, decide how the lost level is preserved — usually as a tag or a title prefix.
JSON to CSV Converter Flatten nested API responses into a reviewable sheet -
Map permissions and audience segmentation
Map public, logged-in, and role-restricted visibility to Confluence's model. Verify the mapping deliberately: internal content accidentally published publicly is the highest-severity failure in this whole category.
Permission mapping errors publish internal documentation to the open web. Verify visibility on every restricted article after load.
-
Build the complete old-to-new URL map
Produce a row per article mapping the old URL to the new one, then confirm exactly where the 301s will be served — Confluence, a CDN, or your own web layer. Without this artifact the redirect step cannot be executed at all.
-
Define the markup conversion and link-rewrite rules
Specify how each markup construct converts and how internal links are rewritten using the URL map. Write it as a repeatable transform, not manual edits — you will run it more than once.
Data Format Converter Reshape the export into the format Confluence's importer expects -
Plan localisation and freeze the spec
Confirm how translated articles link to their source language in Confluence, then version and sign off the mapping spec.
Zendesk Guide → Confluence specifics
- 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
- Internal links
- Rewrite Zendesk article links to Confluence page links using <ac:link><ri:page ri:content-title="Page Title" /></ac:link>
Don't move on until
- Article schema and taxonomy mapped
- Permission and audience model mapped to target equivalents
- Complete URL map produced and redirect method confirmed
04 Test Migration Pilot the hardest articles, then read them.
Objective A pilot load whose formatting, links, assets and search all hold up under human review.
Keep these open
-
Configure Confluence with the agreed structure
Create the category tree, permission groups, locales and branding before loading. Articles loaded before their categories exist land uncategorised and have to be moved by hand.
-
Pick the most difficult articles as the pilot
Choose 20-50 articles for difficulty: the longest, the most heavily formatted, ones with tables and code blocks, deep internal linking, many images, embedded video, restricted visibility, and non-Latin scripts. Easy articles prove nothing.
-
Run the conversion and load with link rewriting
Apply the markup conversion, rewrite internal links from the URL map, upload and re-reference assets, then load. Log every conversion warning rather than suppressing it.
-
Read every pilot article side by side
Open source and target together and compare rendering. This step is manual on purpose: no automated check catches a table that collapsed into a paragraph or a code block that lost its indentation.
-
Click every link and load every asset
Verify each internal link resolves, each image loads from the new host, each attachment downloads and each embed plays. Assets still served from the old CDN are the defect that surfaces only after decommissioning.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Test search and permissions
Search for known terms and confirm the right articles rank, then verify every restricted pilot article is invisible to an anonymous browser. Test permissions from a logged-out session, not an admin one.
Don't move on until
- Complex articles render correctly with formatting intact
- Every internal link and asset in the pilot resolves
- Search returns sensible results for the pilot content
05 Cutover Publish, redirect, and keep the search traffic.
Objective All in-scope content live in Confluence with redirects serving and search engines informed.
Keep these open
-
Load the full content set ahead of the switch
Run the full conversion and load into Confluence, unpublished or on a staging domain. Content migration differs from data migration here: you can stage the whole thing before anyone sees it.
-
Publish the runbook with the redirect step first-class
Sequence the freeze, final delta, publish, redirect activation, sitemap submission and link updates, with owners for each. Redirect activation is the step with lasting commercial consequences, so it gets explicit ownership.
-
Freeze editing and migrate the delta
Stop editing in Zendesk Guide, then convert and load anything changed since the full load. Announce the freeze to every team that publishes — content teams are used to editing whenever they like.
-
Publish and verify permissions live
Publish the content set, then immediately verify restricted articles are not publicly reachable using an anonymous session. Do this before announcing the new site, not after.
Verify restricted content from a logged-out browser. An admin session will show you everything and tell you nothing.
Migration Validation Tool Confirm the final delta landed before you reopen -
Activate 301 redirects and submit the sitemap
Turn on the redirects from the URL map, then spot-check a sample of high-traffic old URLs and confirm each returns 301 to the right article. Submit the new sitemap and keep the old one reachable until search engines have recrawled.
Redirect chains and redirect loops both leak ranking. Verify each redirect resolves in a single hop.
-
Repoint in-product and support links
Update help links embedded in your product, in support macros, in email templates and in onboarding material. These are the links your existing customers actually use, and they are easy to forget.
Don't move on until
- All content loaded, categorised and correctly permissioned
- 301 redirects live and verified from a sample of old URLs
- Sitemap submitted and support links repointed
06 Validation Watch traffic, links and search rankings for weeks, not hours.
Objective Verified content completeness, healthy redirects, and search traffic recovered to baseline.
Keep these open
-
Reconcile content counts and assets
Compare article counts by category and status, plus asset counts, against source. Confirm every article in the keep list is present and every retired one genuinely is not.
Migration Validation Tool Reconcile Zendesk Guide and Confluence record-for-record -
Crawl the new site for broken links and assets
Run a full crawl for 404s, broken images and missing attachments, and fix everything it finds. Repeat the crawl after the fixes rather than assuming they worked.
-
Verify the redirects at scale
Test every mapped old URL for a single-hop 301 to the right destination. Chains and loops both leak ranking and are invisible unless you check the whole map, not a sample.
-
Monitor organic traffic and rankings for four to eight weeks
Track organic sessions, impressions and rankings for your top articles against baseline. A dip in the first two weeks is normal; one that has not recovered by week six is a redirect or indexing problem to investigate.
Do not decommission the old platform until search traffic has recovered — you may still need the old URLs to diagnose a ranking loss.
-
Verify search, permissions and feedback loops
Confirm on-site search returns good results for real queries, re-verify restricted content from a logged-out session, and check article feedback and analytics are collecting.
-
Sign off and decommission on a delay
Get acceptance against the Discovery criteria, keep Zendesk Guide available read-only until traffic has recovered, take a final export, and only then close the account.
-
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.
Zendesk Guide → Confluence specifics
- 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.
Don't move on until
- Article counts reconciled and no broken links remain
- Redirects returning 301 with no chains or loops
- Organic traffic recovered to within tolerance of baseline
Field mapping reference
The field-by-field mapping for each object. Use this as the starting point for your mapping spec.
Zendesk Guide Confluence
| Zendesk Guide field | Confluence field | Notes |
|---|---|---|
| Help Center (Brand) | Space | One Space per Help Center brand |
| Category | Top-level Page | Parent page that groups sections |
| Section | Child Page (container) | Page with child pages for articles |
| Subsection (Enterprise) | Nested Child Page | Confluence nesting is unlimited |
| Article | Child Page (leaf) | Actual content page |
Zendesk Guide Confluence
| Zendesk Guide field | Confluence field | Notes |
|---|---|---|
| category.name | Top-level Parent Page Title | String sanitization |
| section.name | Parent Page Title | Direct mapping |
| section.description | Parent Page body (intro text) | Optional — add as page excerpt |
| article.title | Page Title | Ensure uniqueness within Space |
| article.body | Page Body (storage format) | HTML → XHTML conversion; rewrite <img> tags |
| article.author_id | Page creator | Map Zendesk User ID → Atlassian Account ID |
| article.created_at | Page Properties macro metadata | Cannot set via Confluence API |
| article.updated_at | Page Properties macro metadata | Cannot set via Confluence API |
| article.label_names | Page Labels | Direct mapping via label API |
| article.section_id | Parent Page ID | Map section → parent page from lookup table |
| article.locale | Page label or language suffix | Confluence has no native per-page locale |
| article.draft | Page status | Create as draft page in Confluence |
| Inline image URL | <ac:image><ri:attachment> | Download, upload as attachment, rewrite reference |
| Internal article link | <ac:link><ri:page> | Rewrite using article ID → page ID lookup |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Articles (Body Content) | high | Article HTML must be fully transformed into Confluence's proprietary XHTML storage format with custom XML elements, and raw HTML pushed directly will break the Confluence page editor. |
| Inline Images | high | Images hosted on Zendesk's CDN will become inaccessible after decommissioning and must be downloaded, re-uploaded as Confluence attachments, and have their references rewritten to ac:image macros. |
| Internal Links | high | All cross-article links reference Zendesk URLs that will become dead links, requiring a post-migration remapping pass with a complete ID lookup table. |
| Categories and Sections | medium | Zendesk's rigid Category → Section hierarchy has no direct equivalent in Confluence's flexible page tree, requiring deliberate architectural decisions on Space and parent-page structure. |
| Labels and Tags | low | Zendesk article labels can be mapped directly to Confluence page labels via the API with minimal transformation required. |
| Article Metadata (Timestamps, Authors) | medium | Created and updated timestamps and author attribution can be extracted from Zendesk's API but may not be preserved natively during Confluence page creation without additional API configuration. |
| Table Formatting | medium | HTML tables in Zendesk articles may render incorrectly in Confluence if not converted to the correct XHTML storage format table markup, especially with complex or nested tables. |
| Article Attachments | medium | File attachments associated with Zendesk articles must be separately downloaded and re-uploaded to the corresponding Confluence pages, as attachment hosting is not transferable. |
| Permissions and Visibility | high | Zendesk's article-level visibility settings (agents, signed-in users, everyone) do not map to Confluence's space and page permission schemes, requiring manual reconfiguration to maintain access control intent. |
| Localized Content (Translations) | medium | Zendesk Guide supports article translations per locale, but Confluence has no native multi-language article model, requiring either separate pages or third-party localization plugins. |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
HTML to XHTML Conversion
Zendesk Guide stores article bodies as rendered HTML, which must be transformed into Confluence's proprietary XHTML storage format with custom ac: namespace elements for macros and layouts before pages can be created.
Inline Image Re-hosting
All inline images are hosted on Zendesk's CDN and will 404 once the instance is decommissioned, requiring each image to be downloaded, uploaded as a Confluence attachment, and rewritten from standard img tags to ac:image macros.
Content Hierarchy Mapping
Zendesk Guide's rigid Category → Section → Article structure must be mapped to Confluence's flexible Space → Page → Child Page model, with no enforced one-to-one correspondence between the two hierarchies.
Internal Link Rewriting
Article-to-article links pointing to Zendesk URLs must be programmatically updated by building a lookup table mapping old Zendesk article IDs to new Confluence page IDs after migration.
API Rate Limit Management
Both the Zendesk Help Center API and the Confluence REST API enforce rate limits that constrain throughput, requiring careful throttling and retry logic for large-volume migrations.
Permission Model Differences
Zendesk Guide's article-level visibility model (agents, signed-in users, everyone) does not map directly to Confluence's space-level and page-level permission schemes, requiring manual reconfiguration of access controls.
What breaks
Known failure modes. Have a recovery plan for each before you cut over.
Images:
Zendesk inline images will 404 once your Zendesk instance is decommissioned. Quick fix: Download all images during export, upload them as Confluence attachments, and rewrite the <img> tags to <ac:image> macros.
Formatting:
Pushing raw HTML into Confluence will break the page editor. Quick fix: Transform all HTML into valid Confluence storage format (XHTML) before loading.
Links:
Internal article-to-article links will point to dead Zendesk URLs. Quick fix: Build a lookup table of old Zendesk IDs to new Confluence Page IDs and update the links programmatically post-migration.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Can I export Zendesk Guide articles directly into Confluence?
No. There is no native Zendesk-to-Confluence export or connector. Zendesk's Knowledge Connector syncs Confluence content into Zendesk, not the reverse. Zendesk's CSV export only includes metadata — not article HTML, images, or attachments. You need API-based extraction, a third-party tool, or a managed migration service to move content from Zendesk Guide to Confluence.
What are the Zendesk Help Center API rate limits for article extraction?
Rate limits depend on your Zendesk plan: Suite Team gets 200 req/min, Growth and Professional get 400 req/min, Enterprise gets 700 req/min, and Enterprise Plus gets 2,500 req/min. The incremental articles endpoint has a stricter limit of 10 requests per minute but returns up to 1,000 articles per page, making it the most efficient bulk extraction method.
Why can't I just paste Zendesk HTML into Confluence pages?
Confluence uses a proprietary XHTML-based storage format with custom XML elements (ac:structured-macro, ac:image, ri:page) — not standard HTML. Pushing raw HTML into the storage format field may render initially but will corrupt the page editor and break macros, images, and layouts on subsequent edits.
How do I map Zendesk Guide's category hierarchy to Confluence?
Map Zendesk Categories to top-level parent pages in a single Confluence Space, Sections to child pages under those parents, and Articles to leaf child pages under sections. This preserves the hierarchy without creating excessive Spaces, which become an admin burden in Confluence. If you have multiple Zendesk brands, create one Space per brand.
How do I preserve inline images when migrating from Zendesk to Confluence?
You must download each image binary from Zendesk's CDN, upload it as a Confluence page attachment, then rewrite the article XHTML to reference the new attachment ID instead of the old Zendesk URL. If you migrate the raw HTML as-is, images will 404 when you decommission Zendesk.