Zendesk to Docusaurus without losing SEO

A Zendesk help center that has been live for a few years usually ranks for a long tail of how-to queries nobody on the team tracks. Moving it to Docusaurus keeps that traffic only if every old article URL answers with a permanent redirect to its new home on the day you switch. How you do that depends on one question most teams have not asked yet: who controls the domain the help center is served from?

This guide covers that question first, then export, conversion and the redirect layer, with the Zendesk-specific details that generic migration advice skips.

Understand the URLs you are leaving

Zendesk help center article URLs follow a fixed pattern:

/hc/en-us/articles/360001234567-How-to-reset-your-password
/hc/en-us/sections/360000111222-Account-settings
/hc/en-us/categories/360000333444-Getting-started

Three properties of that pattern shape the whole redirect plan:

• The numeric ID is the stable part. The text after it follows the title and changes when someone renames the article. Zendesk's own Redirect Rules API documentation asks you to omit that slug and match on the ID alone, and you should do the same.
• The locale is in the path. Every language you publish has its own set of URLs, so a help center in three languages needs three sets of rows.
• Sections and categories have URLs too, and they collect links from inside the product and from support replies. They need redirects to the new section index pages, not to the home page.

Build your source list from these patterns plus real traffic: analytics, search console pages with impressions, and a crawl. The general method is in our post on redirect mapping for docs migrations.

The domain question decides the strategy

There are two common setups, and they lead to different plans.

Setup	Example	Who controls redirects after cutover	Strategy
Host-mapped custom domain	help.example.com/hc/...	You, through DNS and your new host	Point the domain at the new site and serve 301s at the edge
Zendesk subdomain	example.zendesk.com/hc/...	Zendesk	Keep Guide running and use Zendesk redirect rules

If the help center is host-mapped, you are in the better position. After cutover, the custom domain points at your Docusaurus host, and your edge or server answers the old /hc/... paths with 301s. You control the status codes, you can test them, and you can keep them indefinitely.

If it is on a Zendesk subdomain, the old URLs live on a domain you cannot repoint. Your options are to keep Zendesk Guide active and create redirect rules there, or to accept losing the rankings attached to those URLs. Many teams keep Zendesk for ticketing anyway, so the first option is often cheaper than it sounds.

Zendesk redirect rules, if you need them

Zendesk has a Redirect Rules API for help centers. At the time of writing, its developer documentation says the following; check it again before relying on it, because plan details change:

• A rule has a redirect_from path, a redirect_to target and a redirect_status, where 301 is one of the allowed values. Creating a rule needs a Guide admin.
• redirect_from omits the article slug, so /hc/en-us/articles/360001234567 is the form to use.
• redirect_to can be a relative path or a full URL, so it can point at your new Docusaurus site.
• A redirect only fires when the original object returns a 404, which means the article must be archived or deleted first.
• There is a limit of 50,000 rules per brand, and the API is available on Guide plans except Guide Lite Legacy.

A single rule looks like this:

curl -s -u "$ZENDESK_EMAIL/token:$ZENDESK_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://example.zendesk.com/api/v2/guide/redirect_rules" \
  -d '{
    "redirect_rule": {
      "redirect_from": "/hc/en-us/articles/360001234567",
      "redirect_to": "https://docs.example.com/account/reset-password",
      "redirect_status": 301
    }
  }'

Generate these from the same CSV you use for everything else, and archive each article only after its rule exists, so there is no window in which the URL returns a plain 404.

One more Zendesk-specific check: before archiving articles, list every Zendesk feature that reads from your help center. Anything that suggests or quotes help center articles, whether to agents inside the ticket view or to customers in a widget or bot, loses its source when the articles are archived. Which of those you have depends on your plan and setup, so make the list from your own admin settings, and decide what replaces each one before cutover, not after.

Export the articles through the API

For a full export, we use the Help Center API, because a script against it can be rerun right up to cutover. The Articles API lets you list articles for a locale, by section or category, and there is an incremental export endpoint that returns articles whose metadata changed since a given time:

# All English articles, cursor pagination (-g stops curl globbing the brackets).
curl -sg -u "$ZENDESK_EMAIL/token:$ZENDESK_TOKEN" \
  "https://example.zendesk.com/api/v2/help_center/en-us/articles?page[size]=100" \
  > articles-001.json

# Articles changed since a Unix timestamp: useful for the final re-sync.
curl -s -u "$ZENDESK_EMAIL/token:$ZENDESK_TOKEN" \
  "https://example.zendesk.com/api/v2/help_center/incremental/articles?start_time=1758931200"

Keep the article id, html_url, title, section_id, label_names, updated_at and body for every article. The ID and URL feed the redirect map; the section ID feeds the new sidebar; the labels are a rough first pass at tags.

The body is HTML. Two things in it need attention before conversion. Inline images are usually hosted by Zendesk, and they stop resolving when the help center is closed, so download every image and rewrite the references. And agents often paste styled content from other tools, which leaves nested spans and inline styles that a converter turns into noise. Strip them first. The handbook page on redirect mapping and the one on converting to Markdown cover the rest of that pipeline.

Map the structure, then the metadata

Zendesk's structure is categories, then sections, then articles, with optional nested sections on some themes. That maps well to Docusaurus: categories become top-level folders, sections become subfolders or sidebar categories, and articles become pages. Resist copying it one to one if the audit shows the structure has drifted; the migration is the cheapest moment to fix it.

Carry the SEO metadata across deliberately:

• Titles. Keep the article title as the page title unless the audit flagged it. A title that already ranks is an asset.
• Descriptions. Zendesk themes often generate meta descriptions from the first lines of the body. Write real description front matter for the pages that carry traffic.
• Locales. If you publish in several languages, use Docusaurus i18n so each language has its own URL space, and map each Zendesk locale path to its Docusaurus equivalent.

Serve the redirects at the edge

For a host-mapped help center, key the redirects on the article ID. In nginx, a named capture from the location plus a map from ID to target keeps the config readable even with thousands of rows:

# Generated from redirects.csv: Zendesk article ID -> new path.
map $zd_id $zd_target {
    default        "";
    360001234567   /account/reset-password;
    360009876543   /billing/update-payment-method;
}

server {
    location ~ ^/hc/[a-z-]+/articles/(?<zd_id>\d+) {
        if ($zd_target = "") { return 404; }
        return 301 $zd_target;
    }
}

An unknown ID returns a real 404 rather than a redirect to the home page. A home-page redirect for everything hides mistakes and is treated by search engines much like a 404 anyway. Instead, make sure every ID with traffic has a row, and let the test script prove it.

Test, switch, watch

Run the redirect test against staging, then against production minutes after the DNS change: every old URL should return one 301 to a page that returns 200. Submit the new sitemap, then watch search console coverage and your 404 logs weekly for the first month. Expect some movement in rankings while search engines process the change; a flat 404 count is the signal that matters.

Update the links you own at the same time. Support macros and saved replies in Zendesk, in-product help links and onboarding emails should point at the new URLs directly. Redirects are the safety net, not the plan.

Get help with the move

If your help center is large, multilingual or on a Zendesk subdomain, the redirect plan is where we would spend the most care. Our Zendesk to Docusaurus migration service covers the export, conversion, redirect map and tests, and we often pair it with support-ticket mining so the new site fixes the content gaps the old one had. The support tickets to knowledge base method explains that part. Tell us your help center URL and rough article count through the contact page. We reply within 1 business day.