Skip to content

从 GitBook 迁移

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.

GitBook 和 Astro 之间的主要相似之处

Section titled GitBook 和 Astro 之间的主要相似之处

¥Key Similarities between GitBook and Astro

GitBook 和 Astro 有一些相似之处，可以帮助你迁移项目：

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

  • Astro 和 GitBook 都支持 Markdown。你可以利用 GitBook 的 Git 同步功能迁移所有现有文档。

  • Astro 和 GitBook 都使用某种形式的 基于文件的路由。将 Astro 的文件结构用于现有内容以及添加新页面时应该感觉很熟悉。

GitBook 和 Astro 之间的主要区别

Section titled GitBook 和 Astro 之间的主要区别

¥Key Differences between GitBook and Astro

当你将 GitBook 文档迁移到 Astro 时，你会注意到一些重要的差异：

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

  • GitBook 站点是使用在线仪表板进行编辑的。在 Astro 中，你将使用 代码编辑器 和开发环境来维护你的站点。你可以在计算机上进行本地开发，也可以选择云编辑器/开发环境，例如 StackBlitz、CodeSandbox 或 Gitpod。

  • GitBook 将你的内容存储在数据库中。在 Astro 中，你的 项目目录 中将为每个页面的内容提供单独的文件（通常为 Markdown 或 MDX）。或者，你可以选择使用 适合你内容的 CMS 并使用 Astro 来获取和渲染数据。

  • GitBook 在 Markdown 之上使用自定义语法来获取内容。Astro 通过可选的 标记文档集成 支持 Markdoc，其语法与你在 GitBook 中使用的语法类似。

从 GitBook 切换到 Astro

Section titled 从 GitBook 切换到 Astro

¥Switch from GitBook to Astro

要将 GitBook 文档站点转换为 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.

你可以将 --template 参数传递给 create astro 命令，以使用我们的官方启动器之一启动一个新的 Astro 项目。或者，你可以 从 GitHub 上任何现有的 Astro 存储库启动一个新项目。

¥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

有了新的 Astro 项目后，你可以将现有的 GitBook 内容同步到新的 Astro 项目。GitBook 有一个 Git 同步功能，它会自动将你的 GitBook 内容同步到 GitHub/GitLab 存储库。

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

要直接同步到文档模板的内容集合，请指定 src/content/docs/en 或 src/content/docs 作为项目目录。

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

同步内容后，你的 Astro 存储库中现在将拥有 GitBook 内容的副本。禁用 gitsync 以防止将来与 GitBook 同步。

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

请注意，虽然你现在已将内容迁移到 Astro 项目，但它不会立即可用。要在 Astro 站点中使用此内容，你需要花一些时间手动将 GitBook 的语法更改为与 Astro 兼容的格式。尤其：

¥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 的 标记文档集成 要求文件扩展名是 .mdoc。这是为了避免与其他 Markdown 扩展（如 .mdx 和 .md）发生冲突。

  • GitBook 语法与 Markdoc 不同，对于 GitBook 文件，表示结束标记的 / 前缀被替换为 end。你将需要在整个文件中更新此符号。

  • GitBook 的某些功能依赖于自定义组件。这些组件不会存在于 Astro 中，必须通过 Markdoc 的配置 tags 属性 创建并添加到你的项目中或从你的文件中删除。

社区资源

Section titled 社区资源

¥Community Resources

  • 添加你自己的！

More migration guides

Astro 中文网 - 粤ICP备13048890号