# Import from GitBook

An import fills a new library from a GitBook space's Git repository: pages, folders, images and files, links between pages and between spaces. Every page keeps its address.

## What you need

GitBook can sync a space to a Git repository (GitHub or GitLab). That repository, as a **zip**, is what Docs Ahoy imports. On GitHub: **Code**, then **Download ZIP**.

The zip must contain:

- `SUMMARY.md`: the table of contents. It decides which pages are imported, their order, their titles and their nesting. Without it the import stops.
- The Markdown files `SUMMARY.md` lists, usually with a `README.md` as the home page.
- The images and files the pages use (GitBook keeps them in `.gitbook/assets/`).

A `.gitbook.yaml` is honoured when present (its `root` and the names of the summary and readme files). The zip can be up to 200 MB; each image up to 10 MB and each other file up to 20 MB.

## Step by step

1. Create a new library for it: an import only goes into an empty library. Choose its default language: every imported page goes into that language.
2. On the library's page, choose the repository zip. It is uploaded and read; **nothing is written to the library yet**.
3. **Review** what the import will create, and answer its questions (below).
4. **Start the import.** The page shows its progress: creating folders and pages, uploading images and files, converting blocks and HTML, linking pages.
5. Read the **import report**, then publish the library when you are happy with it.

While an import runs, the library is locked: it can't be edited or published. Your team runs one import at a time.

## The review

Before anything is written, the review shows:

- **What will be imported**: the number of pages, of images and files, and of images that will be downloaded from other websites. If the zip seems to hold several languages, it says so: all pages go into the default language, and translations can be set up afterwards.
- **Placeholders in angle brackets**: GitBook pages often use words like `<event>` as placeholders. For each one, choose whether it becomes inline code, a plain word, or stays as typed.
- **Links to other GitBook spaces**: links that point at another space. Give each space a name; its links resolve once you import that space here too.
- **Not recognised**: HTML or GitBook blocks we don't support. They are kept as text and listed in the report.

**Start the import** to go ahead, or **Cancel the import**: the zip is dropped and the library is empty again.

## What the import converts

GitBook's blocks become ours (see [Blocks](https://docsahoy.docsahoy.eu/docs/writing/blocks)):

| In GitBook | Here |
| --- | --- |
| Hints | Hints, in the same four tones |
| Steppers | Steppers |
| Expandable sections | Expandable sections |
| HTML tables | Markdown tables |
| Highlights | Highlights, in their colour where we have it |
| Page links and content references | Page references and page cards |
| Images, figures, files | Assets, figures, file downloads |

Tabs become one section after another, each under its tab's title. Footnotes go into the text, in parentheses. The report lists every such change.

## The import report

When the import is done, its page shows the report, which you can also download as Markdown:

- **Imported**: how many pages, folders and files came across.
- **Needs your attention**: anything that didn't: a file the table of contents lists but the zip lacks, a link that was already broken, a file that isn't in the table of contents, an image that couldn't be downloaded, a page too large to import. "Nothing" here means every page, file and link came across.
- **Changed addresses**: pages whose address had to change (a file name that isn't a valid address, for example). Their old addresses forward to the new ones.
- **Converted, with small differences**: table cells joined, footnotes moved into the text, hints with a style we don't have, and similar.

## Links between spaces

If your GitBook spaces link to each other, import each one into its own library. A link to a space that isn't imported yet waits; once that space is imported, its links resolve. **Re-scan links** on the import page resolves waiting links again.

## If an import fails

A failed import says why. Delete the library in its settings and import again: an import can always be repeated.