# From GitBook

> Sync your GitBook space to GitHub, import the repository, and review one commit that turns GitBook blocks into Typemark components. Your Markdown, images and redirects come with you.

GitBook can write each space to a GitHub repository with Git Sync. Typemark imports that repository: it reads `SUMMARY.md` for your navigation and converts GitBook's blocks, such as `{% hint %}` and `{% tabs %}`, into Typemark components.

Unlike a Mintlify import, a GitBook import changes your pages, because GitBook's block syntax only renders on GitBook. All changes land in one commit, so you can review them on GitHub and undo them with Git.

## Before you start

- You can turn on Git Sync for the space. It's available on GitBook's plans that include it; check your plan in GitBook.
- The repository is 100 MB or smaller and has no Git submodules.
- Use a new, empty repository for the sync. The import commits to it, and you don't want GitBook writing to the same files afterwards.

## Import your space

<Steps>
  <Step title="Sync the space to GitHub">
    In GitBook, open the space, set up **Git Sync** with a new GitHub repository, and choose the direction **GitBook → GitHub** for the first sync. The other direction would replace your space with the empty repository.
  </Step>
  <Step title="Create a Typemark project">
    Click **New project**, name it, and under **Start from** choose **Import from GitHub**. Click **Create and connect GitHub**, and give the Typemark GitHub App access to the repository.
  </Step>
  <Step title="Pick the repository">
    Typemark shows **GitBook space detected** with the `SUMMARY.md` it found. Click **Import** and confirm.
  </Step>
  <Step title="Review the conversion commit">
    Typemark writes `typemark.json`, converts every page in one commit, pushes it to GitHub and builds your site. The project overview shows the [import summary](https://docs.typemark.dev/migrating/overview#the-import-summary).
  </Step>
  <Step title="Turn off Git Sync in GitBook">
    Disconnect Git Sync for the space so GitBook stops writing to the repository.
  </Step>
  <Step title="Go live">
    Work through the [go-live checklist](https://docs.typemark.dev/migrating/overview#go-live-checklist), then click **Go live** in **Settings** > **Publishing**.
  </Step>
</Steps>

Several spaces, languages or variants? Sync each one to its own repository and import each as its own Typemark project. To publish languages as one site instead, put each translated page in a folder named after its language code, at the same path as the page it translates, in one project. See [Languages](https://docs.typemark.dev/configuration/languages).

## What the conversion looks like

<CodeGroup>
````md getting-started.md (GitBook)
---
description: Install the SDK.
---

# Getting started

{% hint style="warning" %}
Node 18 or later is required.
{% endhint %}

{% tabs %}
{% tab title="npm" %}
```bash
npm i @acme/sdk
```
{% endtab %}
{% endtabs %}
````

````mdx getting-started.mdx (Typemark)
---
title: Getting started
description: Install the SDK.
---

<Warning>
Node 18 or later is required.
</Warning>

<Tabs>
<Tab title="npm">
```bash
npm i @acme/sdk
```
</Tab>
</Tabs>
````
</CodeGroup>

## What gets converted

| GitBook | Typemark |
|---------|----------|
| `SUMMARY.md` page groups (`## Group`) | Groups in `typemark.json` navigation |
| Nested pages in `SUMMARY.md` | Pages in the same group, right after their parent, since Typemark groups don't nest |
| `.gitbook.yaml` `root` | [`docs_root`](https://docs.typemark.dev/configuration/typemark-json#docs_root), when the space isn't at the repository root |
| `.gitbook.yaml` `redirects` | `redirects` |
| Pages listed in `SUMMARY.md` | `.mdx` pages. Pages not listed are left as they are and named in the summary |
| `folder/README.md` | `folder.mdx`, so `/folder` keeps working. The space's readme becomes the first page, at `/` |
| `SUMMARY.md` | Removed: your navigation now lives in `typemark.json` |
| The first `# Heading` of a page | The page `title` in frontmatter |
| `description`, `hidden` frontmatter | Kept |
| `{% hint style="info" %}` | `<Info>` |
| `{% hint style="success" %}` | `<Check>` |
| `{% hint style="warning" %}` | `<Warning>` |
| `{% hint style="danger" %}` | `<Danger>` |
| `{% hint style="tip" %}` | `<Tip>` |
| `{% tabs %}` and `{% tab title="…" %}` | `<Tabs>` and `<Tab title="…">` |
| `{% stepper %}` and `{% step %}` | `<Steps>` and `<Step title="…">`, titled from the step's heading |
| `{% code title="…" %}` around a code block | A code block with that title |
| `<details>` and `<summary>` | `<Accordion title="…">` |
| `{% columns %}` | `<Columns>` |
| Cards tables (`data-view="cards"`) | `<CardGroup>` with a `<Card>` per row |
| `<figure>` with a caption | `<Frame caption="…">` |
| `{% embed url="…" %}` of a YouTube, Vimeo, Loom, or Wistia video | A [`<Video>`](https://docs.typemark.dev/components/videos), with the embed's caption |
| Any other `{% embed url="…" %}`, `{% content-ref %}`, `{% page-ref %}`, `{% file %}` | A card linking to the same address |
| `{% openapi … path="…" method="…" %}` | An `<API>` endpoint block |
| Links to other `.md` pages | Links to the Typemark page, from the site root |
| Files in `.gitbook/assets/` | Moved to `images/`, with every link updated. Names with spaces get dashes |
| `{% include %}` reusable content | Copied into each page that uses it |
| `space.vars` and `page.vars` expressions | Replaced with their values |

## Not carried over

- **Organization-level OpenAPI specs.** Add the spec file to the repository and list it in navigation as a `{ "source": "openapi.yaml" }` entry. See [OpenAPI](https://docs.typemark.dev/api-reference/openapi).
- **Visitor authentication, integrations and site customisation** that live in GitBook's settings rather than the repository.
- **`{% swagger %}` blocks** stay as text and are listed. Generate endpoint pages from the spec file instead.
- **Blocks Typemark doesn't know** stay as written and are listed in the summary, with the pages that use them.

## From your terminal

To convert a synced repository on your computer instead:

```bash
cd my-gitbook-repo
typemark migrate             # detects the GitBook space and converts it, then offers to create the project and push it
```

Answer yes twice and your site is on Typemark, offline until you publish it. In CI or with a coding agent, use `typemark migrate --create "My Docs" --push` instead.

`typemark migrate` writes the same changes as the GitHub import. Commit or stash your work first, so you can review the result with `git diff`.

## With your coding agent

For what's left, such as unknown blocks or custom HTML, let your coding agent finish the job:

```bash
typemark migrate --from gitbook --agent claude
```

See [With your coding agent](https://docs.typemark.dev/migrating/other).
