---
title: "From GitBook"
description: "Export GitBook through Git Sync and migrate Markdown, SUMMARY navigation, assets, spaces, and hosted behavior"
canonical_url: "https://docs.farming-labs.dev/docs/migrations/gitbook"
markdown_url: "https://docs.farming-labs.dev/docs/migrations/gitbook.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 1650
  task: "Export a GitBook site through Git Sync and migrate it into Farming Labs Docs."
  outcome: "GitBook pages, table of contents, assets, and representable blocks render in a buildable Farming Labs Docs project, with hosted-only behavior tracked."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "Create or obtain a complete GitHub or GitLab Git Sync export for every published GitBook space."
    - "Preserve .gitbook.yaml, SUMMARY.md, README files, assets, redirects, and site structure."
    - "Record dashboard-only domains, authentication, variants, search, analytics, and OpenAPI blocks."
  files:
    - ".gitbook.yaml"
    - "SUMMARY.md"
    - "README.md"
    - "docs.config.ts"
    - "docs.config.tsx"
  sideEffects:
    - "GitBook space hierarchy and hosted blocks are converted into repository content and application configuration."
  verification:
    - description: "Build the target and compare every GitBook space, SUMMARY entry, redirect, asset, custom block, and access boundary."
      expect: "The build passes and every required public page is migrated or redirected."
  rollback:
    - "Keep GitBook published and Git Sync connected until the new site and redirects pass verification."
  failureModes:
    - symptom: "Git Sync export is missing pages or spaces."
      resolution: "Export each published space separately and verify its SUMMARY before migrating."
    - symptom: "Exported Markdown contains opaque HTML for a GitBook block."
      resolution: "Replace that block with portable Markdown, a Farming Labs component, or a registered custom component."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Export a GitBook site through Git Sync and migrate it into Farming Labs Docs.
Outcome: GitBook pages, table of contents, assets, and representable blocks render in a buildable Farming Labs Docs project, with hosted-only behavior tracked.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- Create or obtain a complete GitHub or GitLab Git Sync export for every published GitBook space.
- Preserve .gitbook.yaml, SUMMARY.md, README files, assets, redirects, and site structure.
- Record dashboard-only domains, authentication, variants, search, analytics, and OpenAPI blocks.

### Files

- `.gitbook.yaml`
- `SUMMARY.md`
- `README.md`
- `docs.config.ts`
- `docs.config.tsx`

### Side Effects

- GitBook space hierarchy and hosted blocks are converted into repository content and application configuration.

### Verification

- Build the target and compare every GitBook space, SUMMARY entry, redirect, asset, custom block, and access boundary.
  - Expected: The build passes and every required public page is migrated or redirected.

### Rollback

- Keep GitBook published and Git Sync connected until the new site and redirects pass verification.

### Failure Modes

- Git Sync export is missing pages or spaces. — Recovery: Export each published space separately and verify its SUMMARY before migrating.
- Exported Markdown contains opaque HTML for a GitBook block. — Recovery: Replace that block with portable Markdown, a Farming Labs component, or a registered custom component.
<!-- farming-labs:agent-contract:end -->

# From GitBook

## From GitBook task

Task: Export a GitBook site through Git Sync and migrate it into Farming Labs Docs.

Expected result: GitBook pages, table of contents, assets, and representable blocks render in a buildable Farming Labs Docs project, with hosted-only behavior tracked.

## From GitBook prerequisites

- Create or obtain a complete GitHub or GitLab Git Sync export for every published GitBook space.
- Preserve .gitbook.yaml, SUMMARY.md, README files, assets, redirects, and site structure.
- Record dashboard-only domains, authentication, variants, search, analytics, and OpenAPI blocks.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From GitBook verification

- Build the target and compare every GitBook space, SUMMARY entry, redirect, asset, custom block, and access boundary. Expected: The build passes and every required public page is migrated or redirected.
- Failure: Git Sync export is missing pages or spaces.
- Recovery: Export each published space separately and verify its SUMMARY before migrating.
- Rollback: Keep GitBook published and Git Sync connected until the new site and redirects pass verification.

## From GitBook agent guidance

Require a Git Sync export for every published space. Read .gitbook.yaml to resolve root, readme,
summary, and redirects, then parse SUMMARY.md as the navigation source of truth. Site sections,
variants, permissions, domains, analytics, and other dashboard settings require a separate
inventory because they may not exist in Git.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).