Migration
Migrating off GitBook without carrying the drift across
In short
The mistake in most documentation migrations is treating the old site as the thing to preserve. A page-for-page export carries the staleness across with everything else. The alternative is to use existing docs as a seed for structure and voice, regenerate reference content from the repository, and use coverage to confirm nothing was lost.
The trap in a documentation migration
Every migration starts the same way: someone exports the existing site, gets a folder of Markdown, and treats the job as getting that folder to render somewhere new.
It's a reasonable instinct and it produces a bad outcome, because it makes an assumption nobody said out loud — that the old documentation was correct. If your reference pages had drifted from the code, the export preserved that drift perfectly. You now have the same inaccuracies on a faster platform, plus a migration project in the rear-view mirror that everyone believes fixed the documentation.
That last part is the expensive bit. A migration resets the internal clock. Nobody audits docs that were just migrated.
Why "move it, then fix it" doesn't happen
The plan is always to clean up after the cutover. It rarely survives contact with the quarter.
The migration itself consumes the appetite for documentation work. The team that just spent three weeks on redirects and theme configuration is not volunteering for a content audit in week four, and the pages that need it most are the ones nobody wanted to own in the first place — that's why they drifted.
There's also no forcing function. After a migration everything renders, the links resolve, and the site looks better than it did. Nothing in that experience surfaces the parameter that was renamed eight months ago. The docs look healthy, which is precisely the failure mode of documentation drift.
Four things to decide before you start
Most migration pain traces back to a decision that got deferred rather than made. Settle these first and the rest is mechanical:
- What is your source of truth? If the answer is "the docs site," you will migrate the same problem you have now. If the answer is "the repository," the migration has a direction and the rest of these get easier.
- Which pages are actually load-bearing? Pull your analytics. Most doc sets have a long tail that nobody reads and that everybody feels obliged to carry across. Migrating fewer, better pages beats migrating all of them.
- What happens to your URLs? Decide the new structure before you build it, and map every existing path to a destination. Redirects planned afterwards are redirects done badly, and search equity is the thing a migration is most likely to lose permanently.
- Who reviews the regenerated reference? Someone has to look at the diff between old and new and confirm the new version is right where they disagree. Naming that person before you start is the difference between a migration and a re-migration.
A better sequence
Split the doc set by what can be derived and what can't, then treat each half differently.
Carry the authored content across
Conceptual explanation, architectural narrative, tutorials, onboarding guides — none of this is derivable from source, all of it represents real judgement about what a reader needs, and it should migrate as-is. This is the part of your documentation that was genuinely expensive to write.
Regenerate the reference from the repository
Endpoints, parameters, types, configuration options, and CLI surface get generated from source rather than exported. The old pages are useful here as a seed for structure and voice, but the code decides what's true. Anything that had drifted gets corrected in the process, without anyone having to find it first.
Verify the examples
Documented commands and API calls are executed against your live deployment, and mismatches are reported. On a migration this is where you learn what the old site was quietly getting wrong — usually more than expected, and usually in the quickstart, which is the page that matters most.
Use coverage as the completeness check
Comparing page counts before and after tells you almost nothing, because the old site may have had gaps too. Coverage against the actual public surface is the stronger measure: it tells you what's documented relative to what exists, not relative to what used to be documented.
What this looks like in practice
- Inventory what's authored vs. what's reference. Usually a faster exercise than expected — most teams know which pages a person wrote and which were maintained under duress.
- Connect the repository and run an initial generation to see what the reference looks like when derived from source.
- Diff it against the old reference. This is the interesting artifact of the whole migration: the delta is a direct measurement of how far the docs had drifted.
- Bring authored pages over and edit where the new structure warrants it.
- Map redirects from every old URL before cutting over. Non-negotiable — this is where migrations lose search equity that took years to build.
- Point your domain and let subsequent pushes keep it current.
When this isn't the right fit
Some doc sets shouldn't migrate this way:
- Mostly hand-authored, little code surface. If your documentation is overwhelmingly conceptual, regeneration has little to work with and you're better served by a straightforward content migration.
- Non-engineering documentation. Internal policy, HR, or process content isn't derived from a repository and doesn't belong in this workflow.
- Languages outside the supported set. TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, and Ruby.
- Mid-launch timing. A migration during a major release is two risky changes at once. Ship the release, then migrate.
Frequently asked questions
Will we lose content we wrote by hand?
No — and you shouldn't want to. Conceptual explanation, architectural narrative, and tutorials are the parts that aren't derivable from source, so they carry across and stay authored. What gets regenerated is the reference material.
How long does a migration take?
Initial generation runs in minutes once a repository is connected. The work that takes real time is deciding what to carry over and reviewing the result — which is the part worth spending time on.
What about our existing URLs?
Map them. Any migration that changes URL structure needs redirects from the old paths, or you hand back the search equity the old site accumulated. Plan this before you cut over, not after.
Can we keep our own domain and branding?
Yes. Published documentation runs on your custom domain with your branding.
How do we know the new docs cover everything the old ones did?
The repository dashboard reports coverage across your public surface. That's a stronger check than comparing page counts, because it measures against the code rather than against the old site — which may have had gaps of its own.
Is this only worth doing if we're unhappy with our current platform?
Not necessarily. The question worth asking is whether your reference docs are accurate today. If the answer is uncertain, that's a content problem, and moving platforms without addressing it just relocates it.