从Gitbooks迁移到Hugo

新版gitbooks已开始全面收费，cli工具也不再继续更新，gitbooks已不适合部署开源项目的文档。虽然旧版的gitbook工具可以满足绝大部分的需求，但为了后续开发，需要选择一款新的文档生成器。
Hugo是一款使用Go开发的静态网站生成工具，结合社区开发的丰富主题，可以很方便地开发文档网站。因为Hugo与gitbook一样使用Markdown编写内容，所以从Gitbooks迁移到Hugo十分简单。

目录结构

gitbook使用一个单一的文件SUMMARY.md表示目录结构，与内容文件的目录结构无关。在Hugo中网站的目录结构与内容的目录一致。
如果gitbook中文件目录结构与文档目录结构一致，迁移时无需修改目录结构，只需要将父目录对应的文件名修改为_index.md即可。

文件内容

将每个文件的标题改成Hugo的文件头Front Matter，并加入weight参数，填入该页面在目录中的序号。

title: 文件标题
weight: 2

主题

强烈推荐hugo-theme-learn

部署

参考Hugo文档《Host on GitHub》

示例

请访问《ecCodes GRIB教程中文版》
文档源代码：perillaroc/eccodes-tutorial-cn

图片

如果章节中含有图片，则需要额外的处理。

在上面的图片中，原有gitbook的图片都保存在 02-grib-tools 的 asset 文件夹下。但将其转为 Hugo 后，只有 _index.md，即 02-grib-tools 的目录章节，与原有的 asset 在同一个路径下/02-grib-tools/，其余子页面均在子路径下，例如/02-grib-tools/copy\_messages/。所以文档中的 asset 目录指/02-grib-tools/copy_messages/asset，不是/02-grib-tools/asset。
如果不想修改文档中的图片链接，可以将文档章节放到一个单独的文件夹中，Hugo 将其称为 Page Bundle。将文档移动到该目录下，并改名为 _index.md，同时将需要的图片放到该目录下的asset目录中。类似上面图中的 grib_keys 目录。这样，就可以编译后的网站就正常访问图片了。