Migration guide
Migrate from GitBook to Octri
The move starts from two things a GitBook site already has: the OpenAPI file its API blocks read, and the Markdown that Git Sync keeps in your repository.
Written by Octri · Checked 25 October 2026
What to have to hand
Your OpenAPI file, and your Markdown in a GitHub repository. Everything else is set in API Studio and SDK Studio.
- openapi.yaml
- Markdown from Git Sync
What comes across
GitBook has no config for Octri to read, so the move runs on files you already have. Rows marked “By hand” are what is left for you.
| What | In Octri | From GitBook |
|---|---|---|
| API reference | A page for every endpoint, written for you | Your OpenAPI file |
| Guides | Page drafts, by Pull from GitHub | Markdown from Git Sync |
| Redirects | octri.json | Your site redirects |
| Logo, colours and fonts | Set in API Studio | By hand |
| SDKs | Generated in the languages you pick | Nothing to bring |
Step by step
Bring the spec
Sign up and upload the OpenAPI file your GitBook API blocks read, or connect the repository it lives in. The reference is written for every endpoint, so the API blocks are no longer needed.
Pull your guides from GitHub
Connect the repository that holds the Markdown that GitBook’s Git Sync writes, then choose Pull from GitHub in the API Studio Files panel. Pick up to 50 Markdown or MDX files at a time and each lands as a page draft, with its title, description, icon and badge taken from the frontmatter. Switch on sync on push and later edits in Git keep landing on the same pages.
Swap GitBook blocks
GitBook blocks are written as template tags. They have direct counterparts, listed in the table below.
Set up your SDKs
Pick your languages in SDK Studio, and the call through each SDK appears on every endpoint page. Give each language the package name your users already install, and publish the first Octri release as a new major version, since method names and types can change. Every later spec change arrives in the SDK repository as a pull request.
Keep your old links working
Open
octri.jsonin the Files panel and add a redirect for each old path, starting with the ones in your GitBook site redirects. A rule that ends in/*covers a whole section, and a project keeps up to 500 of them.Go live
Publish, then point your custom domain at Octri last, so readers keep the old site until the new one is ready. From then on every merged spec change rebuilds the draft of your docs, SDKs and MCP tools, ready for you to publish.
Tags that change name
| GitBook | Octri |
|---|---|
| {% hint %} | <Callout> |
| {% tabs %} and {% tab %} | <Tabs> and <Tab> |
| {% stepper %} and {% step %} | <Steps> and <Step> |
Questions
No. The importer only reads the files you upload, and Pull from GitHub only reads your repository. Nothing is written back to either, so your current site keeps running until you move the domain.
Still deciding?
The comparison sets Octri against GitBook row by row, from each product’s own pages, with Octri’s prices beside them.
Other migration guides
Migrate from
Stainless
Targets, package name, repository and method names from stainless.yml and your spec.
Read the guideMigrate from
Speakeasy
Languages, SDK name, package name and x-speakeasy extensions from workflow.yaml and gen.yaml.
Read the guide
Migrate from
Fern
SDK generators, package name, docs theme and the page list from the fern folder.
Read the guide
Migrate from
liblab
Spec, languages, auth schemes and package name from liblab.config.json.
Read the guide
Migrate from
Mintlify
Name, theme, spec and the page list from docs.json or mint.json, plus your MDX by Pull from GitHub.
Read the guide
Migrate from
ReadMe
Your OpenAPI file and the Markdown that bi-directional sync keeps in Git.
Read the guide
Migrate from
Redocly
Your bundled OpenAPI file, your Markdown in Git and the redirects in redocly.yaml.
Read the guide
Migrate from
Scalar
The OpenAPI document from your Scalar registry or repository, and your Markdown and MDX guides.
Read the guide
Migrate from
Stoplight
The OpenAPI file and Markdown articles in the repository your Stoplight project syncs with.
Read the guide
Migrate from
Docusaurus
The OpenAPI file your plugin reads, your MDX pages and the layout in sidebars.js.
Read the guide
Migrate from
APIMatic
The API definition your SDKs are built from and the Markdown guides in your portal.
Read the guide
Migrate from
OpenAPI Generator
The spec you pass to -i and the package names in your generator config.
Read the guide
Try it on your own spec
Bring what you have from GitBook on the Free plan and see your reference written and your first SDK built.