Skip to content

Migrating from GitBook

GitBook is a web-based platform for creating and publishing documentation and books in a collaborative manner, with version control integration and customizable features.

Key Similarities between GitBook and Astro

Section titled Key Similarities between GitBook and Astro

GitBook and Astro share some similarities that will help you migrate your project:

  • Both Astro and GitBook support Markdown. You can migrate all your existing documentation utilizing GitBook’s Git Sync feature.

  • Both Astro and GitBook use some form of file-based routing. Using Astro’s file structure for your existing content and when adding new pages should feel familiar.

Key Differences between GitBook and Astro

Section titled Key Differences between GitBook and Astro

When you migrate your GitBook docs to Astro, you will notice some important differences:

  • A GitBook site is edited using an online dashboard. In Astro, you will use a code editor and development environment to maintain your site. You can develop locally on your machine, or choose a cloud editor/development environment like StackBlitz, CodeSandbox, or Gitpod.

  • GitBook stores your content in a database. In Astro, you will have individual files (typically Markdown or MDX) in your project directory for each page’s content. Or, you can choose to use a CMS for your content and use Astro to fetch and present the data.

  • GitBook uses a custom syntax on top of Markdown for content. Astro supports Markdoc via the optional Markdoc integration, which features a similar syntax to the one you would use in GitBook.

Switch from GitBook to Astro

Section titled Switch from GitBook to Astro

To convert a GitBook documentation site to Astro, start with our official Starlight docs theme starter template, or explore more community docs themes in our theme showcase.

You can pass a --template argument to the create astro command to start a new Astro project with one of our official starters. Or, you can start a new project from any existing Astro repository on GitHub.

Terminal window
npm create astro@latest -- --template starlight

Once you have a new Astro project, you can sync your existing GitBook content to your new Astro project. GitBook has a Git Sync feature that will automatically sync your GitBook content to a GitHub/GitLab repository.

To sync directly to the docs template’s content collection, specify src/content/docs/en or src/content/docs as the project directory.

After syncing the content, you will now have a copy of your GitBook content in your Astro repository. Disable git sync to prevent future syncing with GitBook.

Note that although you now have your content migrated to your Astro project, it will not be immediately usable. To use this content in your Astro site, you will need to spend some time manually changing GitBook’s syntax into a format compatible with Astro. In particular:

  • Astro’s Markdoc integration requires that the file extension be .mdoc. This is to avoid conflicts with other Markdown extensions like .mdx and .md.
  • GitBook syntax differs from Markdoc where the / prefix denoting a closing tag is replaced with end for GitBook files. You will need to update this notation throughout your files.
  • Some features of GitBook rely on custom components. These components will not exist in Astro and must be created and added to your project through Markdoc’s config tags attribute or removed from your files.

Community Resources

Section titled Community Resources
  • Add your own!

More migration guides