Migrations

Migrating from GitBook

Export GitBook content via Git Sync and rebuild it in Shiso.

GitBook stores content as Markdown with template-style blocks ({% hint %}, {% tabs %}). Export the raw files with Git Sync, then convert the blocks to Shiso components and rebuild the table of contents as docs.json navigation.

What carries over#

Content: Markdown pages, headings, tables, images
Structure: the page tree from SUMMARY.md maps to groups and pages
Assets: files under .gitbook/assets/ move to public/

Migration steps#

Export your content

Enable Git Sync in GitBook to push the space to a Git repository, and clone it. This gives you every page as a .md file plus SUMMARY.md and .gitbook.yaml.

Create a Shiso project

pnpm dlx create-shiso-app@latest my-docs

Copy content and assets

Move the exported pages into content/docs. Move .gitbook/assets/ files into public/images/ and update image paths to /images/....

Rebuild SUMMARY.md as navigation

Each SUMMARY.md section becomes a group; each entry becomes a page path:

{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "pages": ["index", "quickstart"]
      }
    ]
  }
}

Convert GitBook blocks and validate

Rewrite {% ... %} blocks as components (see mapping below) — MDX does not understand the template syntax and will fail on it — then:

pnpm check
pnpm build

Block mapping#

GitBook	Shiso
`{% hint style="info" %}`	`<Info>`
`{% hint style="success" %}`	`<Check>`
`{% hint style="warning" %}`	`<Warning>`
`{% hint style="danger" %}`	`<Danger>`
`{% tabs %}` + `{% tab title="..." %}`	`<Tabs>` + `<Tab title>`
Expandable sections	`<Accordion title>`
`{% stepper %}`	`<Steps>` + `<Step title>`
`{% content-ref %}`	`<Card title href>`
`{% code title="..." %}`	Fenced code block, or `<CodeGroup>`
`{% embed %}`	Plain Markdown link, or `<Frame>` for images

For example:

{% hint style="warning" %}
This can't be undone.
{% endhint %}

becomes:

<Warning>
  This can't be undone.
</Warning>

Frontmatter differences#

GitBook exports may include description frontmatter and take the title from the first # heading. Shiso reads title from frontmatter — add it and remove the duplicate heading:

---
title: Quickstart
description: Optional description shown under the title.
---

Not carried over#

GitBook hosting features — visitor authentication, ask-AI, insights, and integrations; built-in search and the contextual AI menu cover the reader-facing parts
Variants / spaces — model these as tabs or versions
Interactive blocks (API playground, forms) — no equivalent; document APIs with <ParamField> and <ResponseField>

After the move#

Deployment — publish dist/client to any static host
SEO and redirects — map old GitBook URLs to new paths

Last updated on Aug 23, 2026

PreviousFrom MkDocs