Migration guide · Updated
Migrate from GitBook to usedocs
GitBook is great for writing docs. Teams move when the docs are really a customer help center and need to stay current with the product and answer customers directly. Here's how to bring your content across without breaking links.
Short answer
There are two ways to move from GitBook. The GitBook API import brings a whole space and keeps its page groups as collections, but doesn't create redirects. The website import reads your published GitBook site, keeps images and simple tables, and turns every old path into a redirect. For a public help center that already ranks, the website import is usually the better choice.
What moves over from GitBook
Pages
Every page in the space with the API import, or every page the website import can reach from your published site, converted to Markdown.
Structure
The API import keeps GitBook's page groups as collections. The website import builds collections from your URL folders.
Old URLs, with the website import
The website import turns each old path into a redirect to its new article. The API import doesn't record old URLs, so it creates no redirects.
How to move from GitBook to usedocs
- Choose the import. If your GitBook docs are public and get traffic, use the website import for redirects. If they're private or you want GitBook's exact grouping, use the API import.
- For the API import, get a token and space ID. Create a personal access token in your GitBook settings and copy the space ID from the space's URL. In usedocs, open Help center, then Import, choose GitBook, and enter both.
- For the website import, paste your docs URL. In usedocs, open Help center, then Import, choose Any docs site, and paste your published GitBook URL. Choose whether to import as drafts or publish right away.
- Review, connect GitHub, turn on the assistant. Check the drafts, install the GitHub app so merged pull requests propose edits, and turn on Ask AI or the widget.
- Point your docs domain at usedocs. If your docs are on your own domain, point it at usedocs or serve the help center from a subfolder of your site. Old paths imported by the website import redirect to the new pages.
What happens to your links and search rankings
To keep links and rankings, the old URLs need redirects on a domain you control. The website import records every old path and redirects it to the new article once your docs domain points at usedocs. If your GitBook docs live on a gitbook.io address, you can't redirect those; update the links you control.
If you used the API import and your docs were public, add redirects for your most visited old pages in Help center, Redirects, before switching the domain.
What usedocs does once your docs are in
GitBook users usually already think of docs alongside code, and usedocs builds on that habit without making writers use Git. Connect the GitHub repository for your product, not your docs, and right after the import you get a drift report: which articles disagree with the code, each with a suggested fix. From then on, merged pull requests propose edits to the articles they change, and questions readers ask that the docs can't answer become drafted articles.
Limits worth knowing
- Website import: up to 100 pages per run; run it again per section for bigger sites, and pages already imported are skipped.
- API import: no redirects, because it doesn't record old URLs.
- GitBook specific blocks, like tabs and expandable sections, come across as plain content to tidy up.
- Interactive API blocks don't carry over; OpenAPI files can be imported as articles separately.
When to stay on GitBook
Stay on GitBook if your docs are mainly written by engineers in Git, you rely on Git sync and change requests, or your audience is developers who want GitBook's API blocks. usedocs is built for a customer help center that keeps itself current.
FAQ
Does usedocs keep my GitBook structure?
The API import keeps GitBook's page groups as collections. The website import builds collections from your URL folders.
Will my GitBook links keep working?
With the website import, yes, on a domain you control: every old path redirects to its new page. The API import doesn't create redirects.
Can I import a private GitBook space?
Yes, with the API import, using a GitBook access token and the space ID.
Does usedocs sync back to GitBook?
No. After the move, usedocs is where the docs live and stay current.
Can I import OpenAPI specs too?
Yes. OpenAPI files can be imported as articles.