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):

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.