从 GitBook 迁移到 Astro

GitBook 是一个基于网络的平台，可用于以协作方式创建和发布文档和书籍，具有版本控制集成和可定制特性。

GitBook 与 Astro 之间有一些相似点，可以帮助你迁移项目：

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

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

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

• GitBook 网站是使用在线控制板进行编辑的。在 Astro 中，你将使用代码编辑器和开发环境来维护你的网站。你可以在本地进行开发，也可以选择像 StackBlitz、CodeSandbox 或 Gitpod 这样的云编辑器/开发环境。

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

• GitBook 在 Markdown 的基础上使用了自定义的语法。Astro 支持通过可选的 Markdoc 集成来支持 Markdoc，其特性与你在 GitBook 中使用的语法类似。

要将 GitBook 文档站点转换为 Astro，可以从我们的官方 Starlight 文档主题模版开始操作，或者在我们的 主题展示中查看更多社区文档主题。

你可以通过 create astro 命令传递一个 --template 参数来启动一个带有我们官方起始器的新 Astro 项目。或者，你可以从 GitHub 上任何现有的 Astro 仓库开始一个新项目。

npm create astro@latest -- --template starlight

pnpm create astro@latest --template starlight

yarn create astro --template starlight

一旦你有了一个新的 Astro 项目，你就可以将你现有的 GitBook 内容同步到你的新 Astro 项目中。GitBook 有一个 Git 同步功能，可以自动将你的 GitBook 内容同步到 GitHub/GitLab 仓库。

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

同步内容后，你现在将在你的 Astro 仓库中拥有一份你的 GitBook 内容的副本。禁用 git 同步以防止未来与 GitBook 的同步。

请注意，虽然你现在已经将你的内容迁移到了你的 Astro 项目中，但它并不能立即使用。要在你的 Astro 站点中使用这些内容，你需要花费一些时间手动将 GitBook 的语法改为与 Astro 兼容的格式。具体来说：

• Astro 的 Markdoc 集成 要求文件扩展名为 .mdoc。这是为了避免与其他 Markdown 扩展名如 .mdx 和 .md 冲突。
• GitBook 语法与 Markdoc 不同，其中表示关闭标签的 / 前缀在 GitBook 文件中被替换为 end。你需要在你的文件中更新这种符号。
• GitBook 的一些特性依赖于自定义组件。这些组件在 Astro 中不存在，必须通过 Markdoc 的配置 tags 属性 创建并添加到你的项目中，或从你的文件中删除。

• 添加你自己的！

更多迁移指南