Skip to main content
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.

​
Choose a method

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 now calls the content containers inside a site sections. Older GitBook documentation and community scripts call them spaces.

​
Export a section with Git Sync

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, choose 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.
The initial sync direction matters. Choosing GitHub → GitBook or GitLab → GitBook replaces your section’s content with the selected branch instead of exporting the section. Confirm that the direction starts at GitBook and targets your empty repository. If you choose the wrong direction, roll back to the revision before the Git Sync operation in the section’s version history.
Keep the synchronized repository unchanged as a migration snapshot. Create a branch or copy for your Mintlify conversion.

​
Migrate a public site

The scraper overwrites existing files in a directory.Run the scraper in an empty directory.
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.

​
Understand the Git Sync export

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.

​
Convert SUMMARY.md navigation

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.
Community scripts can automate the recursive SUMMARY.md mapping. Review their generated file moves and shell commands before running them. A converter must handle missing links, external URLs, duplicate pages, nested groups, and GitBook content roots without overwriting source files.

​
Convert GitBook blocks

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.

​
Convert reusable content

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

​
Migrate sections, variants, and translations

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.

​
Migrate OpenAPI documentation

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.

​
Review your migration

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.

​
Launch your new site

  • 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 deployment 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.

​
GitBook references

Related topics

Migration overviewMigrate from FernMigrate from Document360