> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

## Recommended Workflow

**Export your GitBook space**

In GitBook, go to your space settings and export the content as Markdown.
  **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.
  **Initialize HolyDocs**

Create a HolyDocs config in the same directory:

    ```bash
    holydocs init
    ```
  **Rebuild navigation**

Use your old `SUMMARY.md` structure as the source of truth and recreate the sidebar in `docs.json`.
  **Preview and fix syntax**

Run `holydocs check` and `holydocs dev`, then update any GitBook-specific blocks that did not translate cleanly.
  **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.

## Navigation Mapping

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

**GitBook**

````markdown
    # Table of contents

    ## Getting Started

    * [Introduction](README.md)
    * [Quickstart](getting-started/quickstart.md)
    * [Installation](getting-started/installation.md)
    ````
  **HolyDocs**

```json
    {
      "navigation": {
        "groups": [
          {
            "group": "Getting Started",
            "pages": [
              "introduction",
              "getting-started/quickstart",
              "getting-started/installation"
            ]
          }
        ]
      }
    }
    ```

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

**GitBook**

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

```mdx
    <Callout type="info">
      This is an informational hint.
    </Callout>
    ```

### Tabs

**GitBook**

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

````mdx
    <Tabs>
      <Tab title="JavaScript">
        ```javascript
        const response = await fetch('/api');
        ```
      </Tab>
    </Tabs>
    ````

### Details Blocks

**GitBook**

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

```mdx
    <Accordion title="Click to expand">
      Detailed content here.
    </Accordion>
    ```

## Verification Checklist

After migration, validate and preview your converted project:

```bash
holydocs check
holydocs 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

**SUMMARY.md is more complex than HolyDocs navigation**

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.
  **GitBook blocks show up as raw text**

Search for `{%` in the exported content. Those blocks need manual conversion to HolyDocs components or plain Markdown.
  **Images still point at GitBook CDN URLs**

Download the assets into your docs repo and replace the remote URLs with local `/images/...` paths where possible.
  **Theme and branding did not migrate**

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

## Next Steps

- [CLI migrate reference](/cli/migrate)
- [Configuration Reference](/configuration-reference)
- [Navigation Config](/navigation-config)