The GitBook migration trap

Most teams that decide to leave GitBook - or Confluence, or a folder of Markdown, or any docs tool - reach for the same first step: export everything and import it into the new home. Page for page, heading for heading. It's the natural instinct, and every migration tool is built to reward it.

Your content shows up intact, the table of contents matches, and the project looks done before the day is out. The trouble is that "the pages moved" and "the documentation got better" are not the same thing. In most migrations they're barely related.

To see why, it helps to ask a question the export-import workflow never asks: why are you leaving in the first place?

Treat the old docs as a seed, not a payload

Your existing documentation is enormously valuable - just not as the output. As input, it's the richest signal you have about what your product is, who it's for, and what the docs need to cover.

• The table of contents tells you the shape of the subject.
• The prose tells you the audience and the tone.
• The hard facts stated throughout tell you the constraints any new version must not contradict.

So use it for that. Read the old docs to distill a compact description of intent - product identity, audience, the topics that must be covered, the facts that must hold - and treat that as a seed, not a layout to reproduce.

A seed steers what the new docs are about. It explicitly does not dictate that the new docs mirror the old structure heading-for-heading, because the old structure is part of what you're trying to improve.

Regenerate from the source of truth

With that seed in hand, generate the documentation fresh from the code itself - the actual functions, endpoints, commands, and types, steered by the intent you distilled from the old docs.

The output covers the same topics your readers needed, but it's derived from the source of truth rather than from a years-old snapshot of prose. It's free to organize itself better than the legacy site, and - this is the part that pays off for years - it stays in sync, because it regenerates whenever the code changes. No frozen islands. One maintenance model for the whole site.

This inverts the usual migration. Instead of the old docs being the thing you carry forward and the code being an afterthought, the code becomes the thing you generate from and the old docs become guidance for that generation. The product's actual behavior, not last year's description of it, is what readers end up with.

Then measure what survived - the part everyone skips

Here's the objection, and it's a fair one: "Regenerate from code" sounds great until you realize you have no idea whether the new docs actually cover everything the old ones did.

Verbatim import has one genuine virtue - you can at least see that every page made it across. Regeneration trades that visible completeness for freshness. Unless you close that gap, you're asking people to trust that nothing important got dropped.

So don't ask them to trust it. Measure it. "Did the migration keep everything?" is usually a gut call, but it doesn't have to be.

Git2Docs is built around exactly this approach. Instead of copying your GitBook pages over, it reads them to seed a configuration - product identity, audience, the topics to cover, the facts to hold - then regenerates your documentation from your code so it's accurate today and stays in sync going forward. A coverage validator compares the original GitBook content against the generated docs and reports, topic by topic, what carried over and what didn't.

GitBook migration is now available. Read the launch announcement, or start a free trial to run your migration.