Migrate from GitBook

Move GitBook content to ReadMe by exporting each space, converting GitBook blocks and conditions, and choosing the import workflow that fits your team. You gain the ability to build fully custom MDX components beyond GitBook's block editor, and you can run Guides and an OpenAPI-generated API Reference on one platform with unified versioning.

Choose the easiest migration path

Your situation	Recommended path
You want to evaluate a public GitBook site	Use the Importer with a URL.
You can export GitBook spaces through GitBook Git Sync	Convert the Markdown export and use Git-based import or `rdme@10`.
You have a few pages	Create and review content in the ReadMe editor.
You have variants, conditions, permissions, or a large content set	Ask about Enterprise migration assistance.

GitBook's own Git Sync exports content from GitBook to a repository. ReadMe bi-directional Git Sync is a separate, post-migration workflow that starts with a new, empty repository — it does not import an existing GitBook export.

What doesn't transfer, and what replaces it

What doesn't transfer	Rebuild it with
Custom blocks built in GitBook's editor	Custom MDX components
Page-level visibility rules and permissions	Page-level `hidden` frontmatter, project privacy settings, and Internal Documentation access controls
Conditional content and visitor claims	Recreate the intended behavior per version or page; GitBook's runtime condition evaluation does not carry over
GitBook comments and change-request history (not carried over by export)	Continue content review with Branches and Reviews going forward

Export and inventory GitBook content

Export every required GitBook space through GitBook Git Sync.
Export each variant separately when you publish different versions or languages.
Keep the exported repository unchanged as your migration snapshot.
Inventory SUMMARY.md, .gitbook.yaml, .gitbook/assets/, .gitbook/includes/, OpenAPI files, custom blocks, conditions, access rules, and public URLs.

The export can include content, navigation, assets, and reusable content. Comments, change-request history, visitor claims, and runtime condition evaluation do not transfer and need deliberate review and recreation in ReadMe.

Convert blocks and navigation

Convert GitBook {% ... %} blocks to supported ReadMe MDX or Markdown. Start with representative pages, verify the output, then apply a script to repeated patterns. Move assets, update their references, and search the converted files for remaining {% markers.

Use SUMMARY.md as the source for navigation. For CLI uploads, each new Guide needs title and category.uri; use position and parent.uri to recreate hierarchy. For Git-based import, prepare the supported folder structure and _order.yaml files.

Recreate variants and access rules

Create a ReadMe version for each GitBook variant you will publish. Migrate and review one version before continuing with the others. Recreate visibility, access controls, and conditional content because GitBook's visitor claims and runtime condition evaluation do not transfer automatically.

Upload and review

Upload a validated OpenAPI definition if you have one, then preview Guide content before publishing:

npx rdme@10 openapi validate ./openapi.yaml
npx rdme@10 openapi upload ./openapi.yaml --key="$README_API_KEY"
npx rdme@10 docs upload ./docs --key="$README_API_KEY" --dry-run

An OpenAPI upload creates API Reference content from its operations. Retain workflows and conceptual guidance that do not exist in the definition as Guides. Configure authentication before testing Try It!, and integrate the Metrics SDK separately if you need API-log data in the Developer Dashboard.

Set up redirects and cut over

Build redirects from published GitBook URLs, SUMMARY.md, and traffic data. Under Admin Settings > Error Pages, add rules as oldurl -> newurl, one per line. Verify converted blocks, assets, variants, access settings, API Reference coverage, and high-traffic redirects before changing your domain.

Keep GitBook available until you complete verification and cutover.

Optional: continue in Git

After migration, connect a new empty repository through Settings > Git Connection to use bi-directional Git Sync. Use folders and _order.yaml files to manage navigation in that ongoing workflow.

After you migrate

Run a Docs Audit to check content quality, build guided walkthroughs with Recipes, and use My Developers to see how developers use your API once your Metrics integration is live.

Frequently asked questions

Can we keep our GitBook site up during the migration?

Yes. Nothing about uploading content to ReadMe affects your GitBook space. Keep both available until you're satisfied with the migration.

Can we migrate comments and change requests?

No. Preserve decisions or screenshots that your team needs before you stop using GitBook.

Do GitBook variants automatically become ReadMe versions?

No. Export each variant, create the ReadMe version you need, migrate its content, and recreate its access behavior.

What about our custom blocks?

Rebuild them with custom MDX components. The capability exists, but the implementation model is different, so plan each one as a small, individual piece of work.