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.
Updated Nov 19, 20264 min read
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
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.
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.
Pick the repository
Typemark shows GitBook space detected with the
SUMMARY.mdit found. Click Import and confirm.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.Turn off Git Sync in GitBook
Disconnect Git Sync for the space so GitBook stops writing to the repository.
Go live
Work through the go-live checklist, then click Go live in Settings > Publishing.
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.
What the conversion looks like
---
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 %}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, 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>, 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. - 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:
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:
typemark migrate --from gitbook --agent claude