Moving off GitBook without losing your structure

Good news first: GitBook stores pages as Markdown, so you are not extracting content from a proprietary blob. The parts that need attention are the three files around the Markdown.

SUMMARY.md is the piece worth understanding before you start. GitBook’s own docs put it plainly: the file "defines a space’s navigation" and "mirrors your table of contents". It is not decoration — it is the structure, held separately from the pages.

1. Turn on Git Sync

GitBook’s GitHub and GitLab integration syncs a space to a repository as Markdown, and it is bi-directional — changes in the editor are committed, and commits are pulled back in. For a migration you only need the outbound half.

Point it at a fresh repository rather than an existing one. You want a clean tree that contains only what GitBook produced, so you can see exactly what you are taking.

2. Clone it and look at the tree

Before touching anything, read SUMMARY.md. It tells you the intended reading order, which is the one thing the folder layout does not carry, and you will want it beside you in a minute.

# Table of contents

* [Welcome](README.md)

## Getting started

* [Installation](getting-started/installation.md)
* [Your first project](getting-started/first-project.md)

## Guides

* [Deploying](guides/deploying.md)
* [Troubleshooting](guides/troubleshooting.md)

3. Zip the docs and upload

Zip the repository contents and upload the zip, up to 200 MB. Folders become sections, each .md becomes a page titled from its first heading, and relative links and images are rewritten to keep working.

Here is the thing worth knowing before you start rather than halfway through. We do not read SUMMARY.md. The import reads mkdocs.yml and zensical.toml for site name, description, language and navigation; GitBook’s summary file is a different format and is not one of them.

So the structure arrives in two halves:

• Carried automatically: the folder tree, which pages exist, page titles from their first heading, every relative link between pages, and every image.
• Rebuilt by you: the ordering within each section, and the section groupings that SUMMARY.md expressed with ## headings rather than with folders.

In practice that is one pass with SUMMARY.md open beside the page list, dragging pages until the two match. For a fifty-page space it is about ten minutes. It is not zero, and pretending it were would waste more of your time than the dragging does.

If your GitBook space used folders that mirror the summary — which most do — the second half is nearly empty already. It is the spaces where SUMMARY.md groups pages that live in a flat folder where you will actually be reordering.

The other thing that does not travel is GitBook’s own block syntax. Hints are the common one, and they are not standard Markdown — they are a GitBook extension:

{% hint style="info" %}
This renders as a callout in GitBook.
{% endhint %}

On any standard Markdown renderer that shows up as literal text, braces and all. Two ways to deal with it, both fine:

• Blockquote them. A > blockquote is standard Markdown and reads correctly everywhere. Find and replace the wrappers, keep the text.
• Promote them to a heading. A hint that was doing the job of "Note:" is often better as a short bolded line or a small heading.

Search your exported repository for {% before you upload and you will find all of them at once — hints, content refs, tabs and anything else GitBook wrapped. It is a find-and-replace pass, not a rewrite.

What else to check

• Assets referenced from .gitbook/assets — check a page with images after import.
• API playground blocks, if you used them. There is no equivalent; those pages need writing as Markdown.
• Anything relying on GitBook variables or reusable content, which resolve at their build and not at ours.

The part of a migration that hurts later rather than on the day. Every link anyone has ever shared — support macros, README links, blog posts, whatever a customer bookmarked — points at your current addresses.

If your GitBook docs are on your own domain, this is easy: point the domain at the new site and the paths that match keep working. Add a redirect for the ones that changed while you still remember what changed.

If they are on a GitBook-hosted address, you are changing domain as well as platform, and the old links will eventually stop. Publish on your own domain this time. It is the one decision that makes the *next* migration cheap, whoever it is to.

Three things worth doing in the first week, while the content is fresh in your head.

• Read the search results. Search is built at publish time from your pages; try the five things a new reader would type.
• Fix the titles GitBook chose for you. Page titles came from first headings and some of them were written for a sidebar rather than a search result.
• Export once, immediately. Not because you are leaving — because it tells you what leaving would give you, and you should know that on day one rather than on the day it matters.

If you are still deciding rather than migrating, the full GitBook comparison has the pricing side: GitBook’s free tier is one user with no custom domain, and the first paid step is $65 per site a month plus $12 per user.