---
title: "The Ultimate Knowledge Base Migration Checklist: A Zero-Downtime Plan"
slug: the-ultimate-knowledge-base-migration-checklist-a-zero-downtime-plan
date: 2026-05-05
author: Raaj
categories: [Knowledge Base, Checklist]
excerpt: "A technical knowledge base migration checklist covering API export constraints, formatting preservation, 1-to-1 301 redirects, and zero-downtime cutover."
tldr: "Knowledge base migrations fail at the data layer. Without 1-to-1 redirects, asset re-hosting, formatting validation, and delta sync, you lose SEO and break self-service."
canonical: https://clonepartner.com/blog/the-ultimate-knowledge-base-migration-checklist-a-zero-downtime-plan/
---

# The Ultimate Knowledge Base Migration Checklist: A Zero-Downtime Plan


A **knowledge base migration checklist** needs to go beyond "export articles, import articles." The real process involves preserving URL structures, re-hosting inline images, mapping formatting between incompatible editors, handling API rate limits during extraction, and generating 1-to-1 301 redirects so your organic traffic doesn't fall off a cliff the day after cutover. Skip any of these, and you're looking at 404 errors, broken self-service, spiking support tickets, and months of SEO recovery.

This checklist covers what actually breaks during a knowledge base migration and how to engineer around each failure mode — whether you're moving between Zendesk Guide, Intercom, Confluence, Notion, HubSpot, Freshdesk, Document360, or Help Scout.

If you're also migrating tickets and contacts alongside your KB, see our [helpdesk migration checklist](https://clonepartner.com/blog/blog/helpdesk-migration-checklist/) for the broader scope.

## The Real Stakes of a Knowledge Base Migration

Teams underestimate KB moves because the content looks simple in the UI. Under the hood, every platform stores it differently — and a migration that treats articles as flat text will break in predictable, expensive ways.

- **Customer self-service blackout.** Broken links mean customers can't find answers. Support ticket volume spikes within hours.
- **SEO ranking collapse.** Every article URL that returns a 404 instead of a 301 redirect bleeds link equity. Search engines deprioritize your entire help center domain.
- **AI citation loss.** LLMs and AI Overviews index your published articles. Change URLs without redirects, and your content disappears from AI-generated summaries.

The migration itself often takes days. Recovering from a botched migration takes months.

> [!WARNING]
> If you don't have a field-level mapping file and a redirect map before launch week, you're still planning. You're not ready to migrate.

## Phase 1: Pre-Migration Data Audit and Export Constraints

Before touching an API key, inventory everything you're moving and everything the export path will silently drop.

### What to inventory

Don't estimate from article count alone. Two hundred plain-text FAQs can be easier than twenty articles with tables, private attachments, translations, and hard-coded links.

| Data type | Why it matters |
|---|---|
| Articles + body HTML | Core content. Formatting fidelity depends on source/target editor compatibility. |
| Categories / sections / collections | Hierarchy determines navigation. Mismatches flatten your structure. |
| Inline images + attachments | Images hosted on the source CDN will break after migration unless re-hosted. |
| Internal cross-links | Links between articles use source-platform IDs. They all break on import. |
| Translations / multilingual variants | Each locale is a separate article object in most platforms. |
| Author metadata + timestamps | Original publish dates affect SEO freshness signals. Most importers reset these. |
| Permissions / visibility groups | Private or agent-only articles need separate handling. |
| Version history | Almost never migrated. Decide if you need it for compliance. |

Build a manifest that tracks each content object, its source ID, current URL, locale, visibility, parent container, asset count, and whether it's SEO-critical or compliance-sensitive. This is also the point where you decide what *not* to move.

### Platform-specific export gotchas

**Zendesk Guide.** The Help Center API has its own rate limits, separate from the Support API — 200 requests per minute on Team, 400 on Professional, 700 on Enterprise, and 2,500 on the highest tier. Each article retrieval is one request, but inline images must be fetched separately. For a 2,000-article help center with heavy imagery, extraction can take hours with backoff logic. If your extraction script doesn't handle `429 Too Many Requests` responses gracefully, it will time out and leave you with a partial export. Article attachments are limited to 20 MB each. If articles use content blocks, GET responses flatten them to inline text — and updating the article body can replace block references with flat text. ([developer.zendesk.com](https://developer.zendesk.com/api-reference/introduction/rate-limits/)) Start with [How to Export Data from Zendesk Guide](https://clonepartner.com/blog/blog/how-to-export-data-from-zendesk-guide-methods-limits-formats/) for the full breakdown.

**Intercom.** There is no UI export for articles — you must use the REST API. Article bodies come back as HTML, not Markdown. Certain HTML elements including `div`, `span`, `form`, and `script` tags are stripped or replaced with paragraph tags during export. Intercom's editor supports callout blocks and collapsible sections, but those blocks are not described in the public API formatting guide — treat them as your highest-risk test cases. As of May 2026, Intercom documents both public `/articles` and internal `/internal_articles` endpoints, so scripts that only pull public articles will miss internal knowledge. Always verify against the current API version. Content export jobs expire after two days. ([intercom.com](https://www.intercom.com/help/en/articles/8827044-public-articles-faqs?utm_source=openai))

**Confluence.** HTML space exports exclude blog posts entirely — a documented, long-standing limitation. Attachments land in folders named by internal page ID (e.g., `\download\attachments\xxxxxx`), and you lose the human-readable file-to-page mapping. If your team uses Confluence pages as file repositories where documents are attached but not embedded in the page body, those files vanish during import to most target platforms. ([support.atlassian.com](https://support.atlassian.com/confluence-cloud/docs/export-content-to-word-pdf-html-and-xml/))

> [!WARNING]
> No single Confluence export captures everything. PDF and HTML exports silently drop blog posts and comments. XML exports are the most complete but have size limits — Confluence Cloud site import is capped at 200 MB of uncompressed XML data inside the ZIP.

**HubSpot (as target).** HubSpot's native KB importer does not support tables — it replaces them with a placeholder. Each import is capped at 400 articles. Smart copy (URL-based crawl) is only available for Zendesk, Freshdesk, Help Scout, and Intercom — not Confluence, Document360, or Notion. Side-by-side images get forced into a vertical stack, and custom styled `<div>` elements are stripped.

**Help Scout and Freshdesk.** Help Scout's standard import tool doesn't bring knowledge base articles over; its docs point to the Docs API for custom transfer, and HTML or Markdown imports may need reformatting after upload. ([docs.helpscout.com](https://docs.helpscout.com/article/1495-import-emails-or-tickets-into-help-scout)) Freshdesk lets agents export article lists and properties to CSV, but full article bodies sit in the helpdesk data export's Solutions XML. Freshdesk's API limits are account-wide, plan-based, and even invalid requests count toward the limit.

### Extract and stage inline attachments

Images, PDFs, and videos embedded within articles are hosted on the source platform's CDN. When you migrate the text, the `<img>` tags still point to the old URLs. Once you shut down the old platform, those images break.

**The correct process:**
1. Parse the raw HTML/Markdown of every article.
2. Identify every `src` and `href` pointing to the source CDN.
3. Download the asset locally or to a temporary S3 bucket.
4. Upload the asset to the target platform's media API.
5. Rewrite the HTML tag in the article payload to point to the new CDN URL *before* pushing it to the target platform.

> [!WARNING]
> Relying on a tool that "hotlinks" images during import is a massive risk. Always ensure the migration process physically moves the binary files to the new platform's hosting environment.

## Phase 2: Mapping Formatting, Metadata, and Hierarchies

The structural mismatch between platforms is where most "just move the articles" plans fall apart.

### Formatting fidelity

Every knowledge base platform stores article content differently. Zendesk Guide uses full HTML. Intercom converts headings H3–H6 to H1 and H2 while maintaining hierarchy. Confluence uses a proprietary Storage Format (XHTML with custom macro elements). Notion uses nested JSON blocks.

When you move content between these systems, expect specific breaks:

- **Tables** → HubSpot drops them. Notion converts some Confluence tables to databases (if they contain file attachments) or simple tables.
- **Callouts / admonitions** → Intercom's API doesn't fully support callouts or collapsible elements. Confluence callout macros often degrade to plain text in Notion.
- **Code blocks** → Most platforms preserve inline code, but syntax highlighting languages are often lost.
- **Embedded videos** → iframe-based embeds require the embed URL, not a direct link. Intercom rejects unsupported URLs entirely.
- **Confluence macros** → Most macros are unsupported in target platforms. Notion maps some to the nearest block type (e.g., Expand → Toggle), but complex macros like nested bodied macros, Page Properties, and LaTeX blocks degrade to plain text or are dropped entirely.

To preserve formatting, you must write custom translation layers:

```json
// Example: Translating a Zendesk Callout to a standard HTML div for import
{
  "source_html": "<div class=\"callout callout-info\">Important update</div>",
  "target_html": "<blockquote style=\"background-color: #eef; border-left: 4px solid #00f;\">Important update</blockquote>"
}
```

### Hierarchy mapping

Intercom uses a Collection → Section → Article structure, but articles can exist without a section, creating a simplified Collection → Article hierarchy. Zendesk Guide expects a strict Category → Section → Article structure. Confluence supports arbitrary nesting. Notion handles deep nesting well, but its ZIP-file importer caps at 5 GB (15 GB on request) and the API importer caps at 30 GB and approximately 50,000 pages.

If you're moving from a deeply nested wiki (like Confluence) to a rigid 3-tier system (like Zendesk Guide), you'll have to flatten deeper pages into standard articles or convert them into linked index pages. For strategy on mapping wiki structures, see our [Notion to Confluence migration guide](https://clonepartner.com/blog/blog/notion-to-confluence-migration-guide/).

### Metadata preservation

Most native importers reset article timestamps to the import date and attribute authorship to the admin who ran the upload. This matters for two reasons:

1. **SEO freshness signals.** Google uses the published date as a ranking signal. Resetting 500 articles to today's date sends confusing freshness signals.
2. **Internal accountability.** If you need to know who wrote what and when, that context is gone.

The fix is API-level scripting that explicitly sets `created_at` and `updated_at` fields on the target platform — but not every platform supports this. HubSpot's KB import, for example, maps URL, Title, Category, Subcategory, Keywords, Meta description, Article Body, and Subtitle. Nothing else. If the target doesn't support timestamp overrides, append the original metadata to the bottom of the article body as plain text (e.g., *Originally published by Jane Doe on Jan 12, 2023*).

> [!NOTE]
> Label every field in your mapping as **preserved**, **transformed**, **externalized**, or **dropped**. If a stakeholder asks about a field after go-live, you want an answer in the spreadsheet, not a debate.

A simple manifest tracks the decisions:

```csv
source_id,source_url,target_parent,target_slug,locale,visibility,status,redirect_to
123,/hc/en-us/articles/abc,getting-started,/help/getting-started,en-us,public,published,/help/getting-started
124,/hc/en-us/articles/private-runbook,internal-runbooks,db-failover,en-us,internal,draft,
```

## Phase 3: The SEO and 301 Redirect Strategy

Knowledge base articles often rank highly for long-tail product queries. This phase should be the first thing you plan, not an afterthought.

### Why 1-to-1 redirect mapping is non-negotiable

A **301 redirect** tells search engines that a page has permanently moved, transferring link equity from the old URL to the new one. Google's own site-move guidance is explicit: prepare a URL mapping from old pages to new pages, implement redirects on the old URLs, test them, and avoid irrelevant redirects such as sending many old pages to the homepage. ([developers.google.com](https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes?utm_source=openai))

The damage from missing redirects compounds fast:

- External backlinks from forums, Stack Overflow, partner sites — all dead
- Internal product links pointing to help articles — all broken
- Saved bookmarks from your most engaged users — all 404s
- AI Overviews citing your articles — citations go stale

> [!CAUTION]
> Do **not** redirect all old URLs to your new help center homepage. Search engines treat this as a soft 404 and will not transfer link equity. Every redirect must point to the corresponding article on the new platform.

### Building the redirect map

1. **Export all current article URLs** from the source platform (Zendesk: `/api/v2/help_center/articles.json`; Intercom: `/articles` endpoint; Confluence: space export or REST API).
2. **Record the new URL** for each article on the target platform after import.
3. **Generate a 1-to-1 mapping file** — old URL → new URL, one row per article. If content was merged or removed, redirect to the closest equivalent page or return a clean `404` or `410` when there is no replacement.
4. **Implement server-side 301 redirects** via your CDN (Cloudflare, Fastly), reverse proxy (nginx), or the target platform's redirect rules.
5. **Test every redirect** with a crawler (Screaming Frog, custom script) before DNS cutover.
6. **Keep redirects live for at least 12 months** — ideally indefinitely. Googlebot revisits old URLs for months.

```csv
old_url,new_url,status,notes
/hc/en-us/articles/360001,/help/account-reset,301,exact replacement
/docs/legacy-billing,/help/billing-overview,301,content consolidated
/docs/retired-feature,,410,no replacement
```

### Rewrite internal links before import

Articles link to other articles. If Article A links to Article B using the old URL structure, that link breaks post-migration — even if your external redirects work.

During the data transformation phase, build an index of all old URLs and their new corresponding URLs in the target system. Before pushing Article A to the target, run a regex replace over the HTML body to swap old URLs for new ones. This ensures users navigate the new help center naturally without relying on redirects for internal navigation.

### Sitemap and Search Console updates

After cutover:
- Submit a new XML sitemap containing only the new article URLs.
- Use Google Search Console's "Change of Address" tool if you're also changing the help center domain.
- Update `hreflang` annotations and self-referencing canonicals on the new site.
- Monitor the Coverage report for 404 spikes daily for the first two weeks.
- Check the "Page Indexing" report for redirect errors and crawl anomalies.

For broader SEO migration patterns, our [ecommerce migration checklist](https://clonepartner.com/blog/blog/ecommerce-migration-checklist/) covers the same redirect discipline applied to product and category pages.

## Phase 4: Execution, QA, and Zero-Downtime Cutover

A "big bang" migration — shut down the old system on Friday and pray the new one works on Monday — is an unacceptable risk for enterprise support teams. Zero downtime means customers never hit a broken article, a 404, or a missing image.

### Step 1: Run a full test migration

Never go live on your first attempt. Import everything into a staging environment or draft state on the target platform. Validate:

- Article count matches source (articles, drafts, translations)
- Category/section hierarchy is intact
- Inline images render (not broken references to old CDN)
- Internal cross-links resolve
- Tables, code blocks, and callouts display correctly
- Permission groups are mapped (public vs. agent-only vs. restricted)

Don't sample only clean FAQs. Build a test set that includes the ugliest pages: tables, code blocks, callouts, collapsibles, private articles, multilingual variants, pages with reused assets, and SEO-heavy articles with backlinks. Those are exactly the pages that decide whether the migration is credible.

### Step 2: Fix formatting breaks by traffic priority

Every test migration surfaces formatting issues. Prioritize fixes by traffic — use your analytics to identify the top 50 articles by pageviews and validate those manually.

### Step 3: Run delta syncs

Between your test migration and go-live, your team will publish new articles and edit existing ones. A **delta sync** captures only the changes since the last full migration, avoiding a complete re-import.

A delta sync queries the source API for any articles where `updated_at` is after the date of the initial sync. It extracts only those modified or newly created articles and pushes them to the target system, updating existing records. Zendesk offers a real incremental article endpoint keyed by `start_time` and `end_time`; on other systems, you may need to compare `updated_at` values or hashes yourself. ([developer.zendesk.com](https://developer.zendesk.com/documentation/help_center/help-center-api/understanding-incremental-article-exports/?utm_source=openai))

Run delta syncs daily leading up to launch, and run one final sync just before the DNS cutover. This guarantees your new knowledge base is up-to-date without requiring a content freeze.

### Step 4: DNS cutover and redirect activation

1. Activate all 301 redirects.
2. Point DNS for the help center to the new platform.
3. Verify redirects are resolving in real time (`curl` a sample of old URLs).
4. Confirm the new sitemap is submitted.
5. Spot-check 10–20 high-traffic articles for formatting, images, and internal links.

### Step 5: Post-migration monitoring

For 72 hours after cutover:
- Monitor support ticket volume for self-service failure signals.
- Watch Google Search Console for 404 spikes and crawl errors.
- Check analytics for traffic drops on previously high-ranking articles.
- Verify that AI chatbots and internal search tools are indexing the new URLs.

> [!TIP]
> Keep the old knowledge base in read-only mode for 30 days after cutover. This gives you a rollback path if something surfaces late. Treat launch as a routing change, not the moment the content first appears — the target should already exist, already be checked, and already be searchable before you flip the switch.

## DIY Scripts vs. Automated Tools vs. Managed Migration

There are three paths. Each has real trade-offs.

| Approach | Best for | Watch out for |
|---|---|---|
| **DIY Python/Node scripts** | Small KBs (<200 articles), engineering-heavy teams, simple formatting | Rate limit handling, attachment re-hosting, redirect generation, and ongoing maintenance as APIs change. Internal migrations silently kill product velocity by pulling developers away from core features. |
| **Automated migration tools** (e.g., Help Desk Migration) | Mid-size KBs with standard structure, limited engineering resources | Often limited to supported platform pairs; may not handle custom HTML, internal links, multilingual content, or timestamp preservation. If the tool encounters an API error, it often skips the record entirely. |
| **Managed migration service** | Large KBs (500+ articles), complex formatting, SEO-sensitive content, multilingual, compliance requirements | Higher cost — but you're paying for engineering accountability, not just tool access. |

DIY works when the knowledge base is small and the formatting is simple. But the edge cases — Confluence macros, Intercom callout degradation, HubSpot's table limitation, attachment re-hosting, and redirect mapping — add up fast. A 200-article KB with clean markdown might take a developer two days. A 2,000-article multilingual KB with embedded media, tables, and strict SEO requirements can take weeks of engineering time.

Automated tools handle the standard path well but typically can't solve formatting loss, internal link rewriting, or timestamp preservation. If those matter to your use case, you'll still need custom work.

ClonePartner fits when the risky part isn't authentication or API access but the transformation layer: mixed public and internal knowledge, multilingual structures, custom HTML, broken relative assets, SEO-sensitive URLs, or a launch window that can't tolerate self-service downtime. We handle extraction, formatting translation, image re-hosting, internal link rewriting, 301 redirect generation, and delta sync — so your support team never loses access to documentation and your customers never see a gap.

## What a Zero-Downtime Migration Actually Requires

Zero downtime isn't a marketing term — it's an engineering requirement with specific prerequisites:

1. **Parallel environments.** The new KB must be fully loaded and validated before the old one is decommissioned.
2. **Atomic DNS cutover.** Redirects and DNS changes go live simultaneously.
3. **Delta sync coverage.** Any content published between the full migration and go-live is captured.
4. **Pre-warmed search index.** The target platform's search must be re-indexed before customers arrive.
5. **Rollback plan.** If something breaks post-cutover, you can revert DNS to the old platform within minutes.

If your plan doesn't include a mapping file, a redirect CSV, a sample QA pack, and a delta-sync step, it's not ready. The fastest way to avoid broken self-service is to prove the hard parts on a representative sample before anyone books launch day.

If you're moving the ticketing system alongside the knowledge base, read [How to Do a Helpdesk Migration: The 7-Step Checklist](https://clonepartner.com/blog/blog/helpdesk-migration-checklist/). If your bigger risk is choosing the wrong execution model, start with [How to Choose an Enterprise Knowledge Base Migration Service](https://clonepartner.com/blog/blog/how-to-choose-an-enterprise-knowledge-base-migration-service/).

> Migrating a knowledge base with complex formatting, SEO-sensitive URLs, or multilingual content? Book a 30-minute call and we'll scope your migration — no obligation.
>
> [Talk to us](https://cal.com/clonepartner/meet?duration=30)

## Frequently asked questions

### How do I migrate a knowledge base without losing SEO rankings?

Build a 1-to-1 301 redirect map from every old article URL to its new URL. Implement server-side redirects before DNS cutover, submit a new XML sitemap to Google Search Console, update internal links and canonicals, and monitor for 404 spikes for at least two weeks. Never redirect all old URLs to the homepage — search engines treat that as a soft 404 and will not transfer link equity. Keep redirects live for at least 12 months, ideally indefinitely.

### Can I export internal articles from Intercom via the API?

As of May 2026, Intercom documents both public /articles and internal /internal_articles endpoints, so scripts that only pull public articles will miss internal knowledge. Historically, the internal article endpoint lacked stable API support. Always verify against the current API version before assuming internal articles are exportable. There is no UI export — you must use the REST API.

### Why do images break when migrating to a new knowledge base?

Images break because migration tools often copy the HTML text without downloading the actual image files. The image tags still point to the old platform's CDN. Once you shut down or lose access to the old account, every image returns a broken link. The fix is to download each asset, upload it to the target platform's hosting, and rewrite the HTML tags to point to the new URLs before import.

### Does HubSpot's knowledge base importer support tables?

No. HubSpot's native KB import tool does not support tables — it replaces them with a placeholder. Custom styled div elements and side-by-side images are also stripped or reformatted. Each import is capped at 400 articles, and Smart copy (URL-based crawl) only works for Zendesk, Freshdesk, Help Scout, and Intercom sources.

### What is a delta sync in knowledge base migration?

A delta sync is a targeted migration run that only moves data created or updated after the initial bulk migration. It lets your team keep working in the old knowledge base right up until the final cutover, avoiding a content freeze. You run delta syncs daily leading up to launch and one final sync just before the DNS cutover.