Typemark Documentation

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.

Aktualisiert am 19. Nov. 20264 Min. Lesezeit

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

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

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

  3. Pick the repository

    Typemark shows GitBook space detected with the SUMMARY.md it found. Click Import and confirm.

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

  5. Turn off Git Sync in GitBook

    Disconnect Git Sync for the space so GitBook stops writing to the repository.

  6. 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 %}
---
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>

What gets converted

GitBookTypemark
SUMMARY.md page groups (## Group)Groups in typemark.json navigation
Nested pages in SUMMARY.mdPages in the same group, right after their parent, since Typemark groups don't nest
.gitbook.yaml rootdocs_root, when the space isn't at the repository root
.gitbook.yaml redirectsredirects
Pages listed in SUMMARY.md.mdx pages. Pages not listed are left as they are and named in the summary
folder/README.mdfolder.mdx, so /folder keeps working. The space's readme becomes the first page, at /
SUMMARY.mdRemoved: your navigation now lives in typemark.json
The first # Heading of a pageThe page title in frontmatter
description, hidden frontmatterKept
{% 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 blockA 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 videoA <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 pagesLinks 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 contentCopied into each page that uses it
space.vars and page.vars expressionsReplaced 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

See With your coding agent.