Migrating from GitBook

Move a GitBook docs site into HolyDocs using the current export-and-cleanup workflow.

Overview

GitBook migration is currently a manual export flow, not a one-command conversion. HolyDocs can host the exported content well, but you should expect to:

  1. Export Markdown from GitBook
  2. Initialize a HolyDocs project
  3. Rebuild navigation in docs.json
  4. Clean up GitBook-specific syntax

For most small and medium docs sites, this is still a straightforward migration.

1

Export your GitBook space

In GitBook, go to your space settings and export the content as Markdown.

2

Place the files locally

Extract the export into a working directory in your repo. Keep the original folder around until you have verified the migration.

3

Initialize HolyDocs

Create a HolyDocs config in the same directory:

bash
holydocs init
4

Rebuild navigation

Use your old SUMMARY.md structure as the source of truth and recreate the sidebar in docs.json.

5

Preview and fix syntax

Run holydocs check and holydocs dev, then update any GitBook-specific blocks that did not translate cleanly.

6

Deploy

Once everything looks right locally, connect the repo in HolyDocs and run holydocs deploy.

Current CLI Support

The holydocs migrate gitbook command is intentionally lightweight today:

bash
holydocs migrate gitbook

It prints the current manual export steps. It does not automatically convert SUMMARY.md, .gitbook.yaml, or GitBook block syntax yet.

GitBook commonly uses SUMMARY.md as the navigation source. In HolyDocs, you rebuild that structure in docs.json.

markdown
# Table of contents## Getting Started* [Introduction](README.md)* [Quickstart](getting-started/quickstart.md)* [Installation](getting-started/installation.md)

Map file paths to page slugs by removing the extension. README.md usually becomes introduction.mdx or index.mdx, depending on how you want the URL structure to work.

Syntax Cleanup

GitBook exports often contain syntax that should be rewritten into HolyDocs components.

Hint Blocks

markdown
{% hint style="info" %}This is an informational hint.{% endhint %}

Tabs

markdown
{% tabs %}{% tab title="JavaScript" %}```javascriptconst response = await fetch('/api');```{% endtab %}{% endtabs %}

Details Blocks

html
<details>  <summary>Click to expand</summary>  Detailed content here.</details>

Verification Checklist

After migration, validate and preview your converted project:

bash
holydocs checkholydocs dev

Open http://localhost:3333 and verify:

  • Navigation structure matches the old GitBook layout
  • Pages render without raw GitBook block syntax
  • Images load correctly
  • Internal links still point at valid pages

Common Issues

GitBook allows deeper nesting than most HolyDocs sidebars need. Flatten aggressively where it improves readability, and preserve the full path in the slug if necessary.

Search for {% in the exported content. Those blocks need manual conversion to HolyDocs components or plain Markdown.

Download the assets into your docs repo and replace the remote URLs with local /images/... paths where possible.

GitBook UI settings do not map automatically. Recreate branding in docs.json, especially name, logo, theme, and colors.primary.

Next Steps

Previous Migrating from Mintlify
Next Migrating from Docusaurus
Ask a question... ⌘I