Migrating from GitBook

Migrating from GitBook

bxSites migrate converts a GitBook export - a SUMMARY.md table of contents plus its .md files, GitBook's own on-disk sync format (the same one GitHub/Git Sync writes) - into a bx-sites docs/ tree, in one command. Everything GitBook's content-block system supports maps onto something bx-sites already has (see Content Blocks), so the result isn't a rough draft - it's a working site.

Getting a GitBook export

bxSites migrate reads GitBook's own file layout directly, so any of these works as --source:

• A repository GitBook is Git-Synced to (Space settings → GitSync) - point --source at your local clone.
• GitBook's own Export → Markdown download, unzipped.

Either way, --source should be the directory that directly contains SUMMARY.md.

Running the migration

# 1. Scaffold a fresh bx-sites project (skip this if you already have one)
bxSites new my-docs
cd my-docs

# 2. Migrate the GitBook export into it
bxSites migrate --source=/path/to/gitbook-export

# 3. Build and look at the result
bxSites serve

migrate prints how many pages it converted and, when something needed a judgment call, exactly what and where:

Migrated 14 page(s) from [/path/to/gitbook-export] into my-docs/docs/, wrote my-docs/docs/nav.json

2 item(s) need a manual look:
  - guides/advanced.md: Unsupported GitBook block [{% prompt %}] - left in its original syntax, needs manual conversion
  - guides/layout.md: Column width="one-third" is not a plain length/percentage - dropped, review manually

Nothing is ever silently dropped - a block this tool doesn't know how to convert is left in the migrated file in its original {% %} syntax, so the content is still there and still easy to find (search the migrated docs/ tree for {% once you're done). Re-running migrate overwrites any file or docs/nav.json it wrote before, so it's safe to fix your source export and run it again.

What gets converted automatically

A block shown as a literal fenced example in your GitBook content (rather than used for real) is correctly left alone, not misread as the real thing.

What needs a manual look

A handful of GitBook blocks have no bx-sites equivalent at all and are left in their original {% %} syntax rather than guessed at: Prompt (an AI-generation block - there's nothing to run it against once migrated), Conditional content (GitBook-account-based visibility, not a concept bx-sites has), and the Ask AI search bar. Anything else this tool doesn't recognize - a typo'd block, a GitBook feature added after this tool was written - gets the same treatment: left as-is, reported as a warning.

A few smaller judgment calls are reported the same way: an unrecognized hint style (falls back to note), or a column width that isn't a plain CSS length/percentage (dropped rather than trusted verbatim).

Page icons aren't migrated automatically. GitBook's own docs don't confirm that a page's icon assignment (set via its editor's icon picker) actually survives into a Git-Sync export at all - if a project's exported frontmatter genuinely has an icon field, migrate carries it through opportunistically, but don't expect it for most real exports. Set icons by hand afterward instead - either a page's own frontmatter, or a docs/nav.json entry's own icon - using a named icon from one of the eight bundled libraries (no need to match GitBook's own Font-Awesome-based icons; pick whichever name looks right in Phosphor - any of its six weights - Lucide or Tabler's own gallery).

After migrating

The migrated docs/nav.json is a plain nav override file - edit it like any other, or delete it to fall back to bx-sites' own folder-structure-is-nav-structure convention. From here it's a normal bx-sites project: pick a theme, review bxsites.json, and deploy when you're happy with it.