Migrate from GitBook

Migrate GitBook sections, Markdown, navigation, reusable content, variants, assets, and OpenAPI documentation to Mintlify using Git Sync or the scraper.

Export GitBook content to a Git repository with Git Sync for the most complete migration, or scrape a public GitBook site to create an initial Mintlify project.

Use Git Sync for the primary migration when possible. A GitBook site is made up of sections, and a section can have multiple variants, while Git Sync operates at the section level. Export every section that appears on the published site.

GitBook does not provide direct Markdown downloads for individual pages. To export a section as Markdown:

1. Create an empty GitHub or GitLab repository or an empty branch in a migration repository.
2. In the section you want to export, click Set up next to Git Sync in the section header.
3. From the provider list, click GitHub Sync or GitLab Sync, then authenticate if you have not connected the provider yet.
4. Select the empty repository and the branch for the export.
5. For the initial sync direction, select GitBook → GitHub or GitBook → GitLab.
6. Start the initial sync. When it finishes, clone or download the repository.
7. Repeat for every section, language, or version that you need to migrate.

Keep the synchronized repository unchanged as a migration snapshot. Create a branch or copy for your Mintlify conversion.

mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://docs.example.com

The scraper loads GitBook's rendered navigation, downloads reachable images, converts common blocks, and creates a docs.json. It cannot retrieve private sections, unpublished changes, permissions, comments, or revision history.

Compare the generated project with your Git Sync export when both are available. The scrape is useful for checking rendered block conversion. The export is the better inventory of source content.

GitBook normally creates or uses the following files and directories:

• README.md: Section home page
• SUMMARY.md: Table of contents
• .gitbook.yaml: Content root, structure, and section redirects
• .gitbook/assets/: Uploaded images and files
• .gitbook/includes/: Reusable content

The paths can differ when the GitBook configuration defines another content root, home page, or summary file. Confirm your specific configuration before moving any files.

SUMMARY.md is a nested Markdown list. Convert its headings and links to docs.json navigation:

Remove .md extensions from navigation paths, but do not rename every file before checking links. A page such as guides/README.md can become guides/index.mdx or remain a Markdown file with a different navigation path.

Every Mintlify page also needs frontmatter with at least a title. Add or convert frontmatter as you migrate each page.

GitBook represents many blocks with {% ... %} directives. Convert these directives to Mintlify components.

GitBook exports some custom blocks as HTML because they do not have a Markdown representation. Review every HTML block to verify it functions the same in MDX.

GitBook exports reusable content into .gitbook/includes/ and references it with include directives. Convert each reusable file to a Mintlify snippet, then replace the GitBook include with an MDX import and component.

For example:

import Authentication from "/snippets/authentication.mdx";

<Authentication />

Check reusable content shared across multiple sections. GitBook assigns each reusable block a parent section that owns the content and is the only place that you can edit it. Separate section exports can therefore contain duplicate or cross-section references that need to become a single shared snippet.

A GitBook site publishes one or more sections, organizes related sections into groups, and uses variants for versions or languages. Choose the closest Mintlify navigation model:

• Map product or audience sections to products, tabs, or anchors.
• Map release variants to versions.
• Map translated sections to languages.
• Map independent content collections to separate groups when users do not need a selector.

Record the default variant and every variant slug before changing the domain. GitBook can omit the default variant slug from its public URL, so redirects must account for both the default and explicitly named paths.

Copy .gitbook/assets/ into your Mintlify repository and update relative image and download paths. Review inline images that use HTML for sizing or alignment. Do not leave required production assets on GitBook unless you plan to keep that hosting after your migration.

GitBook redirects can exist in your configuration file and in site-level settings. Collect both sources and convert them to Mintlify redirects. GitBook scopes a redirect in its configuration file to one section, while a Mintlify redirect applies to the published site, so include the former section or variant prefix when necessary.

GitBook can store OpenAPI specifications at the organization level and place generated OpenAPI blocks in sections. The Markdown section export might not be the source of truth for these specifications.

1. Inventory every OpenAPI specification in your GitBook organization.
2. Retrieve the original file, hosted source URL, or specification through the GitBook API.
3. Add the JSON or YAML file to your Mintlify repository.
4. Configure OpenAPI-generated pages.
5. Recreate adjacent explanations from normal GitBook blocks.
6. Compare authentication, server URLs, examples, and GitBook-specific OpenAPI extensions with your Mintlify API pages.

Compare every exported section and SUMMARY.md entry against docs.json, then verify every section, group, variant, and language.

Search your converted files for leftover GitBook syntax: {%, {% end, .gitbook/includes, and the raw HTML blocks that GitBook exports in place of Markdown.

• Set a content freeze on your former site and track every change made to it after your migration snapshot.
• Confirm your production branch and repository on the Git settings page of your dashboard.
• Record your existing DNS records and keep your former site running until you verify your Mintlify site is live.
• Review the navbar, footer, favicon, logo, colors, and typography.
• Review site and page metadata, canonical URLs, and indexing preferences. See SEO and search settings.
• Install any required analytics integrations, and optionally add a custom 404 page.
• If you migrated an API reference, compare endpoint pages, navigation structure, server URLs, authentication schemes, and examples with your former site.
• Preview your exact launch commit in a preview deployment. Check desktop and mobile layouts, pages from every navigation section, search, and your redirects.
• Check the browser console and network tab for any errors on pages that use custom components or scripts.
• Switch your domain with the custom domain guide, which covers the zero-downtime cutover for a domain that already serves documentation.
• After launch, monitor for 404 errors, redirect failures, and build failures.

• Git Sync
• Enable GitHub Sync
• Content configuration
• Content structure
• Reusable content
• Content variants
• OpenAPI
• Add an OpenAPI specification

• Migration overview
• Migrate from Fern
• Migrate from Document360