Skip to main content
NookDocs
Dashboard

Maintaining

Migration playbooks

Moving docs from Mintlify, ReadMe, GitBook, Docusaurus, or a legacy CMS to NookDocs. Phased strategies, what to keep vs rewrite, redirect maps, cutover timing, rollback plans.

Migrating a docs site isn't a copy-paste job. You're moving content AND inbound links AND SEO equity AND writer muscle memory. Doing all four in one weekend is usually a disaster. This guide covers the phased approach that keeps your docs online, your Google rankings intact, and your writers productive during the transition.

The CLI migration command handles the mechanical file-conversion part. This guide is about everything AROUND that.

Why migrate (and why NOT to)

Do migrate when...

  • Current platform pricing scales poorly with team + content size

  • You need AI-native features (llms.txt, MCP, Copy-for-LLMs) your current platform doesn't ship

  • Current platform's editor slows your writers down

  • You want full Git control, not a proprietary lock-in

Don't migrate when...

  • You're hoping a migration will fix your writing quality (it won't — content stays the same, framing changes)

  • You haven't shipped consistently for 6 months (migration doesn't replace discipline)

  • You're 2 weeks before a major product launch (bad timing — migrate in a quiet window)

  • Your team hasn't used the target platform for at least 2 weeks in sandbox (unknown unknowns)

The three-phase approach

Phase 1 — Parallel (2-4 weeks)

New platform runs alongside the old. Content migrated + published to a staging domain (docs-beta.acme.com). Writers author new content in the new platform; old platform accepts minor edits only. No public cutover yet.

Phase 2 — Soft cutover (1-2 weeks)

New platform becomes the canonical. Old platform URLs 301/308 redirect to new platform equivalents. Search Console verified on both domains. Public announcement lands at the end of this phase.

Phase 3 — Old-platform sunset (4-8 weeks)

Old platform content stays accessible via redirects for SEO continuity. After Google has re-indexed (~4 weeks), you can decommission the old platform. Redirect rules stay in place indefinitely.

Don't compress these phases. The redirects need time to take effect in Google's index; your team needs time to absorb the new editor; the URL-change dust needs to settle.

Phase 1 — Parallel setup

Mechanical migration

Run the CLI once against a copy of your old-platform repo:

nookdocs migrate ./old-mintlify-repo --output ./nookdocs-staging

Output: a nookdocs-staging directory with nookdocs.config.json + docs/ + migrated assets. Commit to a new GitHub repo, hook up via the NookDocs dashboard, and deploy to a staging subdomain (staging.nookdocs.site or your own docs-beta.acme.com).

See migrate-from-mintlify for the mechanical conversion matrix.

Content audit during migration

The migration is a forcing function for a content audit you should have done anyway:

What to KEEP

Pages with clear inbound search traffic. Pages referenced from support tickets. Pages covering currently-active product features. The top ~60% of pages by traffic.

What to REWRITE

Pages with high bounce + low engagement. Pages that felt awkward on old platform. Pages mixing Diátaxis modes. Take this chance — reshape the content in the new platform before committing to it.

What to MERGE

Two or three pages that cover overlapping topics. Migration is the moment to consolidate — fewer pages, stronger topical clusters (see SEO guide).

What to RETIRE

Pages with no inbound links + near-zero traffic. Pages covering retired features. Pages nobody's touched in 2+ years. Don't migrate what you'd delete.

Writer training

Two weeks minimum on the new platform before writers switch full-time:

  • Everyone signs in + edits a test page. Muscle memory starts here.

  • Walk through the editor + Git workflow. Especially important when moving from a WYSIWYG platform to MDX.

  • Document internal conventions. Which component for which scenario, which frontmatter fields are required, etc. One short internal page.

  • One writer ships a test page each week. Real publishing, even if to staging. Surfaces issues before cutover.

Phase 2 — Soft cutover

The scary phase. Done right, your users don't notice. Done wrong, Google delists half your content for a month.

Redirect map — the most important artifact

Every URL on the old platform must redirect to its new equivalent. Build the map BEFORE cutover, audit it, test a sample.

Format: two-column CSV.

old_url,new_url
/docs/getting-started,/quickstart
/essentials/markdown,/content/format-text
/essentials/code,/features/code-blocks
/essentials/images,/guides/media
/api-reference/endpoint/list-users,/api-reference/users/list-users
/blog,https://acme.com/blog

Generate the initial map automatically from the old platform's sitemap + the new platform's file structure, then audit by hand. Expect 5-15% of entries to need manual override — the auto-match usually gets 85%+.

Three places to set redirects

Pick the layer that matches your deployment:

DNS layer (preferred when old platform becomes unreachable)

Point docs.acme.com DNS at NookDocs. NookDocs's nookdocs.config.json#redirects handles path remapping. Works if old platform is being fully sunset.

Old-platform redirect config

Most docs platforms support redirects config. Keep docs.acme.com pointed at the OLD platform, configure redirects in old platform to send users to docs.acme.com/new-path (same domain) or https://docs-v2.acme.com/new-path. Preferred when you want to keep the old platform reachable for 4-8 weeks during Phase 3.

CDN / reverse proxy layer (most control)

Cloudflare Workers, Vercel rewrites, or Nginx. Proxy intercepts every request to docs.acme.com, checks the redirect map, returns 301/308 for matches, passes others through to the new platform. Most flexible, most work. Only needed when the other two options don't fit.

Status codes that matter

  • 301 Moved Permanently — older HTTP 1.0. Widely supported.

  • 308 Permanent Redirect — HTTP 1.1. Preserves the request method. Google treats it identically to 301. Prefer 308 for new deployments.

  • 302 / 307 Temporary — don't use for a migration. Temporary tells Google not to transfer ranking signals. You want permanent.

NookDocs's redirects config uses permanent: true → 308. Set it for the migration.

Search Console continuity

Before cutover:

  • Verify new domain in Search Console. docs-v2.acme.com if using a new domain, or verify the same property post-migration if reusing docs.acme.com.

  • Submit the new sitemap. docs-v2.acme.com/sitemap.xml — NookDocs auto-generates.

  • File "Change of Address" if moving to a new domain. Search Console → Settings → Change of Address. Tells Google explicitly that content moved.

After cutover:

  • Daily Search Console checks for 2 weeks. Coverage → Indexed pages should stabilise. If you see a sudden drop, a redirect may be broken.

  • Search traffic drop tolerance: 20-30% for the first month is normal. Should recover within 6-12 weeks. If not, re-audit redirects + freshness signals.

LLM-crawler continuity

AI engines re-crawl on their own schedule (weekly to monthly). After cutover:

  • /llms.txt auto-updates on NookDocs. Verify with curl.

  • Sitemap auto-updates. Same.

  • Custom Accept: text/markdown + X-Llms-Txt headers (when shipped — roadmap) help AI engines discover faster.

Spot-check AI answers weekly for a month. ChatGPT / Perplexity / Claude / Google AI → ask the top 5 questions about your product. Verify citations point at new URLs, not 404s.

Phase 3 — Sunsetting the old platform

4-8 weeks after cutover:

Verify Google re-indexed

Search Console → Coverage → Indexed pages. New-platform URLs up; old-platform URLs dropping as redirects take effect. 80%+ indexed is a good signal.

Verify organic traffic stabilised

Analytics on new platform: traffic trend flat or rising. Traffic drop from the cutover week has recovered.

Verify no remaining traffic to old platform

Old-platform analytics: traffic declining steadily. Under 5% of pre-cutover levels means almost everyone uses the redirect.

Decommission carefully

  • Keep redirects in place indefinitely (301/308 at DNS or CDN layer).

  • Can cancel old platform subscription once redirects are owned by a different layer.

  • Archive the old platform content (git repo) before cancelling, in case you need to refer back.

Rollback plan

If Phase 2 goes badly — traffic tanks, writers can't work, editor breaks — have a rollback ready:

  1. Flip DNS back to the old platform (5-minute TTL so changes propagate fast).

  2. Disable redirects on the new platform.

  3. Writers resume on old platform until issues resolved.

  4. Postmortem, new timeline, retry.

You should be able to roll back within 30 minutes. If you can't, the rollback plan isn't real.

Common migration mistakes

Migration checklist

Print this. Walk through linearly.

Pre-migration (2-4 weeks out):

  • Run CLI migration against current repo → review output

  • Audit content: keep / rewrite / merge / retire

  • Build redirect map (old URL → new URL)

  • Stand up new platform on staging subdomain

  • Writers trained + one test page shipped each

  • Verify nookdocs.config.json settings (theme / colors / SEO / contextual menu)

  • Backup old platform content (git repo cloned)

Cutover day:

  • Flip DNS or CDN rewrite to new platform

  • Verify redirects work for sampled old URLs

  • Verify new platform serves correctly on canonical URL

  • Submit new sitemap to Search Console + Bing Webmaster

  • If new domain: file Change of Address in Search Console

  • Send announcement (blog post + Twitter + users' email list)

Post-cutover (weekly, for 4 weeks):

  • Search Console coverage trend (indexed pages)

  • Analytics traffic trend

  • Support ticket volume (any spikes = hidden breakage)

  • AI engine citation spot-check (ChatGPT/Perplexity/Claude)

  • Broken link audit (lychee or similar)

  • Redirect map audit (any entries receiving traffic but not redirecting correctly)

Sunset (4-8 weeks post-cutover):

  • Old platform traffic under 5% of pre-cutover

  • Keep redirects at DNS/CDN layer

  • Archive old platform content

  • Cancel old platform subscription

  • Retrospective: what went well, what'd we change next time

Related

Was this page helpful?

Last updated August 11, 2026