How to migrate from GitBook to Topicary (2026)

How to migrate from GitBook to Topicary

If GitBook's pricing change is what brought you here, this guide is the practical part. It covers how to get your content out (the genuinely fiddly step), what transfers and what doesn't, and how to rebuild your docs in Topicary, without overselling you. If you haven't decided whether to switch at all, read the Topicary vs GitBook comparison first.

One honest framing before you start: a GitBook migration is not a structure migration. GitBook's reusable blocks, variables, and Adaptive Content are proprietary and don't export as reusable components or conditions, so your content comes out as flat Markdown. That sounds like a downside, but it's mostly why this is simpler than a MadCap Flare migration: there's far less structural metadata to preserve, because there was less of it to begin with. You rebuild the structure in Topicary once, deliberately.

First, decide whether you should move to a CCMS at all

The most expensive migration is the one to the wrong category of tool. Be honest about why you're leaving GitBook, because it changes where you should land.

If your only problem is the bill (and your docs are a single, fairly simple site), you probably don't need a CCMS, and you shouldn't pay for one. The honest options:

• fumadocs: open-source, MDX, built-in API playground, self-hosted. The community favorite for "I just want a nice docs site without the GitBook bill."
• MkDocs (Material): open-source static site generator, mature, huge plugin ecosystem.
• A cheaper hosted doc tool: a handful of budget hosts will run a Mintlify/GitBook-style repo for a fraction of GitBook's per-site + per-user pricing.

Any of those solves "GitBook got too expensive" for a straightforward site. Stop here if that's your whole problem; we'd rather you land somewhere that fits.

Move to a CCMS like Topicary when price isn't the only issue. Look for these signals:

• You paste the same passage (a warning, a prerequisite, a support boilerplate) across dozens of pages and dread updating it.
• You need to publish different content to different audiences, platforms, or product tiers from one source.
• You need a branded PDF and a web portal and maybe in-app help, all from the same content.
• You're consolidating docs that live in multiple places (GitBook plus Notion plus a repo).

If two or more of those are true, a CCMS is an upgrade, not a lateral move, and the rest of this guide is for you.

Why teams are leaving GitBook in 2026

The trigger for most migrations right now is pricing. GitBook retired its old generous free tier and moved to per-site ($65 to $249/mo) plus per-user ($12/mo) billing. Longtime users on r/KnowledgeBaseSoftware describe sharp jumps for the same docs; one team reported going from $16/mo to $109/mo. Trustpilot reviews (1.9/5, 73 reviews, checked May 2026) cite "drastic pricing shifts," billing after cancellation, and refund difficulty.

A second, quieter reason is scale. GitBook added reusable content blocks, variables, and Adaptive Content, but they're shallower than CCMS equivalents: no where-used tracking, no orphan detection, no named variable sets, and conditional content only on the Ultimate plan ($249/site/mo) and filtered visitor-side. Multiple reports also describe GitBook's search and performance degrading past 100 to 200 pages. If price and scale are both biting, that's the CCMS case.

Before you export: audit your GitBook space

Don't start the export until you know what you have. Taking inventory makes the rebuild faster and tells you what won't survive the trip.

• Page count: how many pages across how many spaces. This drives your timeline.
• Git Sync status: is your space already synced to a GitHub repo? If yes, your content is already Markdown and step 1 is nearly done.
• Reusable blocks: list the GitBook reusable content blocks you rely on. These won't export as components; note them so you can recreate them in Topicary.
• Variables: note any GitBook variables/expressions; you'll rebuild these as Topicary variable sets.
• Adaptive Content: if you use visitor-side conditional content, note where. Topicary handles audience splitting differently (publish-time), so you'll rebuild it as conditions.
• GitBook-specific blocks: hints/callouts, tabs, API playgrounds, embeds. These import as raw text or plain content and need manual cleanup.
• What to leave behind: pages untouched in over a year, drafts, duplicates. Every page you don't migrate is one you never have to reorganize. Cut them before exporting.

Step 1: Get your content out of GitBook

This is the step people underestimate. GitBook has no direct "export to Markdown" button; one widely-cited migration post-mortem put it as "getting your content out is harder than getting it in." The supported path is Git Sync.

If you already have Git Sync enabled (easiest)

1. Confirm your GitBook content already exists as Markdown files in the connected GitHub repository.
2. Clone the repo locally: git clone <your-repo-url>.
3. Use that folder of .md files as your content, then move to step 2.

If you don't have Git Sync

1. In GitBook, connect the space to a GitHub repository (Git Sync settings). GitBook writes your content out to the repo as Markdown.
2. Clone the repo as above.
3. Fallback if you can't use Git Sync: copy pages individually. GitBook pages paste into the Topicary editor with basic formatting preserved. Slower, but it works for small spaces.

Step 2: Import into Topicary

Open Topicary's import dialog (drag the folder onto the editor, or use the import button in the project toolbar). Topicary auto-detects Markdown, so there's no need to pick a "GitBook" format, because by this point your content is Markdown.

The importer shows a preview before committing: the files it detected, and the topics they'll become. Drag the whole cloned folder; nested folders are fine. Review the count. If it's far lower than your page count, check that you dragged the content directory and not just the repo root.

Step 3: Verify what transferred

Because the content arrived as Markdown, the structural prose comes through cleanly. Open the project and spot-check:

What transfers: headings (H1 to H6), paragraphs, ordered and unordered lists, tables, code blocks, images, and inline links. This is the bulk of most docs and it lands intact.

What doesn't transfer as structure:

• GitBook-specific blocks: hints/callouts, tabs, API playgrounds, and embeds import as raw text or plain content. Convert hints to Topicary callouts; rebuild API reference from your OpenAPI spec (Topicary imports OpenAPI 3.x directly into structured reference topics).
• Reusable blocks, variables, Adaptive Content: these were GitBook-proprietary and don't carry over as components/variables/conditions. You'll recreate them in step 4, which is the upgrade, not a loss.
• Page hierarchy: recreate it as a Topicary map (drag topics into the tree). This is usually the longest part of the rebuild.

Step 4: Build the structure layer GitBook couldn't

This is the payoff and the reason you're moving to a CCMS rather than another flat host. With content imported, do the things GitBook couldn't:

• Turn repeated passages into components. Select text → "Save as component." Now that warning or prerequisite lives in one place, with where-used tracking and orphan detection. Edit once, update everywhere, and see every topic affected before you change it.
• Add conditions. Tag content by audience, platform, or product tier. Preview filtered in the editor, and publish separate outputs (a Windows guide, a Linux guide) from one source, at publish time, on any paid plan, not visitor-side behind GitBook Ultimate.
• Define variable sets. Replace the GitBook variables you noted in the audit with named Topicary variable sets ({product_name}, {support_email}, {version}) that switch per publication target.
• Add PDF. If you ever needed a branded PDF out of GitBook, you can now generate one (branded cover, TOC, running headers) on any paid plan.

Step 5: Validate and publish

Before you point your public URL at the new site, run the checklist:

• Spot-check 10 to 15 topics across sections: formatting, heading levels, lists, and that images render.
• Check every converted block: confirm hints became callouts and that no GitBook tab/playground content was lost as raw text.
• Open each component and confirm the "Where Used" count matches expectations.
• Preview with conditions applied: toggle each dimension and verify the right content shows and hides.
• Confirm variables resolve to expected values across web and PDF.
• Publish to a draft URL, navigate every page, and check the map hierarchy matches your old GitBook nav.

Keep GitBook live and publishing during this period. Run both in parallel until you've validated every section, then switch your public URL.

Realistic timelines

These assume one person doing the work. The variable is not the import (Markdown lands fast); it's rebuilding the map hierarchy and converting GitBook-specific blocks. Time spent turning repeated content into components in step 4 is optional at migration time; you can do it gradually after launch.

What you gain after migration

• Flat pricing that doesn't scale with headcount. No per-seat creep, no per-site multiplier. The thing that pushed you off GitBook doesn't follow you.
• Real content reuse. Components with where-used tracking and orphan detection: edit once, know exactly what changes.
• Multi-audience, multi-format output. Publish-time conditions and variable sets, plus web, PDF, and Markdown from one source.
• LLM-ready output, structured underneath. Every published site generates llms.txt, llms-full.txt, .md page URLs, sitemap.md, and an AI query endpoint, fed by a structured pipeline, not flat pages.
• SME review without logins or per-seat charges. Send a review link; no GitBook account at $12/user required.

Currently free during beta. Join here. For the full feature and pricing breakdown, see Topicary vs GitBook; for other tools, see the best technical writing software. Moving as a small team? See Topicary for small teams.

Disclosure: This guide is published by Topicary. I compete with GitBook and have a commercial interest in teams migrating. So I've tried to be straight about when a cheaper static host is the better choice, and about what GitBook does not let you export. Pricing checked against gitbook.com/pricing in May 2026; the $16→$109 figure is a user report from migration discussions, not GitBook's published pricing. Found an error? Email support@topicary.com and I'll correct it within 24 hours.