Documentation migration checklist from source to launchDocumentation migration checklist from source to launch

A documentation migration can pass its build and still leave readers with broken bookmarks, missing API versions, or private pages that are now public. The preview is a useful first check, but you need to know what happened to the content and links people already use.

This documentation migration checklist walks through what to save, what to test, and when to switch to the new site. Start with a recoverable copy of the original, map the old URLs, and check the tasks readers need to complete before launch.

The checks apply whether you are moving to Thally or another platform. Adapt them to the versions, languages, and access rules your documentation supports.

1. Save the source and agree on what is moving

Before converting anything, agree on who will review the content and who will switch the hosting. Record the source revision or export date, the destination project, the versions and languages you are keeping, and the planned launch date.

Save the source files, assets, and configuration needed to rebuild the existing site. Decide how to handle edits while the migration is in progress. You might pause edits briefly for a small site, or copy the final changes across just before launch.

Check that the saved copy includes everything you are keeping.

• Pages and navigation cover every version and language you intend to retain.
• Images, downloads, snippets, custom components, and API definitions are accounted for.
• Externally hosted files will remain available, or have been copied to a location you control.
• Unpublished and restricted content is identified separately.
• The content owner has approved anything you are leaving behind.

Do not rely on page counts alone. One API definition can generate many pages, and a public crawl will not tell you whether private pages or unpublished drafts were saved.

2. Check the structure and platform settings

Copying Markdown or MDX does not necessarily copy the navigation, access rules, or interactive components around it. Check the settings as well as the page files.

Source	Material to inspect	What to verify
Mintlify	docs.json, referenced configuration, navigation, components, and API files	The new site preserves the structure and behavior you need.
GitBook	Spaces, exported content or Git Sync files, page hierarchy, and linked assets	Every space you are moving is included, with its page hierarchy.
Docusaurus	Current and versioned docs, sidebars, configuration, components, and translations	Each product version leads to the correct content.

The Mintlify settings reference explains that docs.json controls navigation, integrations, appearance, and API settings. Its $ref support means configuration can depend on additional files.

GitBook Git Sync synchronizes content in both directions with GitHub or GitLab when configured. If you use it as the source, confirm that the latest editor changes have reached the repository. Check all the spaces you plan to move.

Docusaurus distinguishes the current source directory from the version served by default. Preserve versions.json, versioned_docs, and versioned_sidebars where used, then inspect the configured routes. Its versioning guide shows why copying only docs/ can miss released content.

For more detail on the platforms, see our comparisons with Mintlify, GitBook, and Docusaurus.

3. Map old URLs to the new site

Map the URLs readers use, which may differ from the source filenames. Include the version, language, and links to important headings. Record pages you are deliberately removing too.

Here is a small example using hypothetical paths.

Old path	Destination or decision	What to check
/quickstart	Preserve /quickstart	Page loads and setup steps work
/guides/auth#tokens	/authentication#tokens	Redirect reaches the page and the anchor exists
/v1/client	Preserve the v1 guide	Page remains about v1
/old-beta	Return 404 or 410	Owner confirms the page is removed and has no replacement

For a page with a replacement, redirect the old URL to the most relevant new page. The Google site migration guide recommends permanent redirects on the server, such as 301 or 308, along with updated internal links, canonical URLs, and sitemaps. A removed page without a replacement can return 404 or 410. Sending every removed page to the homepage can confuse readers and be treated as a soft 404.

Request the old URLs and check both the response and the page you reach. Look for redirect chains, loops, and links that land on unrelated content. Test links to headings in a browser too. The fragment after the hash is not sent to the server, so a request check alone cannot prove that the heading link works.

If the hostname and paths stay the same, focus on the content and hosting checks in the Google hosting migration guide.

4. Try a few different pages before converting everything

Start with a quickstart, an API operation, a page with tabs or callouts, and a long code example. Add translated and restricted pages if you have them. Include your most visited pages and anything you expect to be difficult to convert.

For each sample, note what worked, what needs fixing, and who will fix it. If the destination does not support a component, decide how to replace it. A callout might become ordinary text. An interactive example may need more work to preserve what the reader can do.

For API docs, preserve the definition and its referenced files. The OpenAPI specification defines how relative references resolve. Moving a YAML file without its dependencies can break the rendered reference.

Check the API paths, methods, authentication instructions, examples, and server URLs. Run example requests in a test environment with test credentials, especially when a request creates or changes data.

5. Review the preview as a reader

Use this table to review the preview. Record the revision, reviewer, date, and result for each check. Leave a check open until someone has completed it.

Check	What needs to work
Build and conversion	The destination builds, conversion warnings are fixed or reviewed and accepted
Content	Instructions, code, tables, images, downloads, and API definitions match the intended source
Navigation and versions	Menus, search results, and version or language selectors reach the right pages
Links and URLs	Internal links resolve and every mapped old URL has the intended outcome
Access	Users who are signed out or lack permission cannot read restricted content, users with permission can
Desktop and mobile	Pages, tables, code, and illustrations remain readable without the whole page scrolling sideways
Keyboard and interaction	Navigation, tabs, search, and copy controls work, with visible keyboard focus
Discovery	Canonical URLs, the sitemap, and production indexing settings use the final URLs

Check search and any outputs used by AI agents, such as published Markdown, llms.txt, or an MCP server. Search for a known page and confirm that the result uses the intended version. Test restricted content through these interfaces too, not only through the website. Our guide to documentation for AI agents explains the available formats.

Reload an existing tab and open a fresh one. If the results differ, check caching and the search index before approving the site. Protect previews that contain private content with access controls. A robots.txt rule or noindex tag does not stop someone from opening a page.

6. Plan the switch and the rollback

Before launch, copy across any final edits and record the exact revision you will deploy. Write down the following decisions so everyone involved knows what to do.

• Name the person making the switch and the reviewer they can contact.
• List the hosting, domain routing, redirects, certificates, search indexes, and integrations that will change.
• Keep the last working deployment, source revision, and routing configuration available.
• Agree on which unresolved problems will block launch, including exposed private content or missing critical guides.
• Define when to roll back, who makes that decision, and the steps to restore the previous site.

Rehearse the recovery steps in a test environment. Decide how to keep edits made after launch if you need to restore the previous site. Keep the old platform available for as long as the rollback plan depends on it.

If URLs changed, keep the redirects running even after retiring the old platform. The Google migration guide recommends keeping redirects for at least a year. Consider keeping them longer when readers still use the old links.

7. Check the live site and assign ongoing ownership

After the switch, repeat the most important reader tasks on the live domain. Check HTTPS, old bookmarks, redirects, images, downloads, permissions, search, and the default product version. Remove temporary indexing blocks from pages that should be public, while keeping restricted content protected.

Watch for failed requests, searches with no useful results, support reports, and indexing problems. Give each issue an owner and a date to check it again. The Google Search Console guide explains its indexing and search performance reports. Save a baseline before the move so you can compare the results.

Make sure someone owns the documentation after the migration. Record where edits happen, how changes are reviewed and published, and who checks the docs when the product changes. Our guide to keeping docs in sync with code covers that ongoing work.

Use the checklist to compare platforms

Try the same sample pages on each platform you are considering. Compare what needs fixing, how publishing works, and what your team will need to maintain. If you are considering Thally, read the documentation or create a site and use the checklist to review it.

Sources and verification

This checklist draws on the linked platform documentation and Google migration guidance. The sample URL map is hypothetical. This article does not report a tested migration or converter benchmark.