# Moving off GitBook without losing your structure

Your pages are Markdown already, so the content is the easy part. The structure lives in a SUMMARY.md and the hints live in GitBook’s own syntax — here is how to get both out with your navigation intact.

_Source: https://docszero.com/resources/moving-off-gitbook_
_how-to · 6 min read_
_Published 10 September 2026_

> **In short:** Use Git Sync to get a repository of Markdown, then keep SUMMARY.md open as your checklist. The pages and folders carry most of the structure; the ordering you rebuild by dragging, once, in about the time it takes to read the summary file.

## What you actually have in GitBook

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.

| File | What it holds |
| --- | --- |
| `SUMMARY.md` | The navigation. Your table of contents, as a nested list |
| `README.md` | The root page of the space |
| `.gitbook.yaml` | How GitBook parses the repo — root, and which file is the summary |
| `.gitbook/assets/` | Images and files referenced by your pages |
| `*.md` | The pages themselves, plus GitBook’s own block syntax |

> `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.

## Getting it out

### 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.

**a typical SUMMARY.md — the headings become sections, the order is the order**

```
# 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.

## The structure part, honestly

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 GitBook-specific syntax

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:

**what you will find in your exported pages**

```
{% 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.

## Do not forget the URLs

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.

## After the move

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](https://docszero.com/compare/gitbook) 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.

## Questions

### How do I export my docs from GitBook?

Use Git Sync, GitBook’s GitHub and GitLab integration, which syncs a space to a repository as Markdown and is bi-directional. Point it at a fresh repository so the tree contains only what GitBook produced, then clone it. You will get your pages as .md files, a README.md, a SUMMARY.md holding the navigation, and assets under .gitbook/assets.

### Does my GitBook navigation transfer automatically?

Partly. The folder tree, the pages, their titles, relative links and images all come across on import. The ordering held in SUMMARY.md does not, because that file is GitBook’s format and the import reads mkdocs.yml and zensical.toml. You rebuild the order by dragging, with SUMMARY.md open beside the page list — about ten minutes for a fifty-page space.

### What is SUMMARY.md in GitBook?

It is the file that defines a space’s navigation — GitBook describes it as mirroring your table of contents. It is a nested Markdown list of links, with ## headings acting as section groups. During a migration it is the most useful file you have, because it records the reading order that a folder layout alone does not.

### What happens to GitBook hint blocks when I migrate?

They arrive as literal text, because {% hint style="info" %} is GitBook-specific rather than standard Markdown. Search your exported repository for {% to find every one at once, then either convert them to blockquotes, which render correctly anywhere, or promote them to a short bolded line. It is a find-and-replace pass rather than a rewrite.

### Will my old GitBook links keep working?

Only if your docs were on a domain you own — then you point that domain at the new site and matching paths keep resolving. On a GitBook-hosted address you are changing domain as well as platform, so those links will eventually break. Publishing on your own domain this time is what makes any future move cheap.

---

Published by Docszero (https://docszero.com) — docs, minus the setup. Upload Markdown, a Word document or a PDF and get a searchable documentation site. Free for one site; export the source on every plan.