Migrate from GitBookCopy Anchor Link

GitBook is hosted, so the first migration step is obtaining a complete Markdown repository through GitHub or GitLab Git Sync. Once exported, SUMMARY.md provides the page hierarchy and .gitbook.yaml describes the content root, entry page, redirects, and summary location.

1. Export through Git SyncCopy Anchor Link

For each published GitBook space:

1. Connect an empty GitHub or GitLab repository.
2. Select the GitBook-to-Git initial sync direction.
3. Wait for Markdown, SUMMARY.md, and assets to appear.
4. Clone the repository and preserve the export commit.
5. Verify the number of pages against the published table of contents.

If a site publishes multiple spaces, sections, or variants, repeat this process for each content source and record how GitBook combines them.

2. Inventory the export and dashboardCopy Anchor Link

Repository inputs:

• .gitbook.yaml
• SUMMARY.md
• configured README.md entry page
• Markdown pages and HTML blocks
• .gitbook/assets/ or other asset directories
• redirects declared in .gitbook.yaml

Dashboard inputs:

• site sections and variants
• custom domain
• authentication and protected content
• search and AI
• analytics
• OpenAPI blocks and API authentication
• redirects managed at the site level

3. Resolve the content rootCopy Anchor Link

Read .gitbook.yaml before copying:

root: ./docs/
structure:
  readme: README.md
  summary: SUMMARY.md
redirects:
  previous/page: new-folder/page.md

All content paths are relative to root. Use the configured readme as the section landing page and the configured summary as the navigation source.

4. Translate SUMMARY.mdCopy Anchor Link

GitBook uses Markdown headings as groups and nested list links as pages:

## Getting started

- [Overview](README.md)
- [Installation](getting-started/installation.md)
  - [Configuration](getting-started/configuration.md)

Create matching directories, use landing pages for groups where needed, and add numeric order frontmatter following list order. Preserve alternate sidebar link titles when they differ from page headings.

Every summary link should become a target route, redirect, or explicit retirement decision.

5. Convert GitBook contentCopy Anchor Link

Standard Markdown usually moves directly. Review:

• GitBook hint and callout blocks
• tabs
• expandable sections
• cards
• stepper blocks
• embedded files, videos, and iframes
• OpenAPI and request blocks
• exported HTML for custom blocks

Prefer built-in Farming Labs MDX components or plain Markdown. Preserve HTML only when the target runtime safely supports it and the behavior is verified.

6. Move assets and redirectsCopy Anchor Link

Copy exported assets into the target public/static directory or keep them beside content when supported. Update encoded filenames and relative URLs carefully.

Translate both .gitbook.yaml redirects and site-level dashboard redirects into the target application or hosting platform. Test old public URLs—not only repository paths.

7. Recreate hosted behaviorCopy Anchor Link

Implement these separately:

• sections and variants → explicit route trees, versions, or locales
• authentication → application middleware and authorization
• custom domain → hosting and DNS
• search and AI → search and ai
• analytics → analytics
• OpenAPI → apiReference
• page feedback and edit links → Farming Labs feature configuration

Comments, revision history, and GitBook workflow state are not page content and do not migrate through Markdown.

8. Validate and recoverCopy Anchor Link

1. Compare every SUMMARY.md link with a target route.
2. Build the target.
3. Test exported HTML blocks, assets, downloads, and embeds.
4. Verify redirects from published GitBook URLs.
5. Test each section, variant, locale, and access boundary.
6. Fetch representative pages through .md.

If pages are missing, stop and correct the Git Sync export before converting content. If a custom block renders incorrectly, replace that block family and verify all pages that use it.

Source referencesCopy Anchor Link

• GitBook migration and export
• GitBook Git Sync content configuration
• GitBook site structure
• Farming Labs sidebar
• Farming Labs configuration