混合方案

tags: 混合

github方案是指采用github提供的git仓库存储书籍内容,并使用gitbook发布HTML内容。

可以说是github + gitbook 的混合。

适合于习惯用github做git仓库,又想使用gitbook提供的功能的情况。

背景

  1. 在github上已经存在gitbook格式的书籍:之前提交并使用github page发布
  2. 想在gitbook网站创建新的书籍,但是内容依然继续存放在github原有的git仓库中

操作

在gitbook网站,登录后点”MYBOOKS” -> “New Book”。

和前面一样先做 1/2/3 这三个步骤,然后点击红色箭头处:

方案4:混合 - 图1

在左边的三个选择中点”GITHUB”, 然后点红色箭头处的下拉框,gitbook会开始链接github获取可选的仓库列表,之后再点下拉框中,就可以选择对应的git仓库:

方案4:混合 - 图2

最后点右下角的”Create Book”,书籍创建成功之后,显示如下:。

方案4:混合 - 图3

表示正在构建书籍的内容,稍等片刻,如果顺利,则显示为build成功。有时gitbook的页面不会及时刷新,可以稍后手工点击”UPDATE”直接看结果:

方案4:混合 - 图4

点”ABOUT”就可以回到书籍首页,再点”READ”可以看到生成的书籍内容的HTML内容。

错误处理

长时间没有build成功

注意: 如果长时间没有build成功,可以打开书籍的”UPDATES”查看情况:

方案4:混合 - 图5

比如上图中最下面的一个build,显示失败,点击最右边的”dc4c59c546”,可以看到详细的build过程日志输出:

  1. Downloading source
  2. Pulling from S3
  3. Extracting source
  4. GitBook version is 3.1.1
  5. Tweaking book.json
  6. Installing plugins
  7. ConfigurationError: Error with book's configuration: config.isbn is not of a type(s) string

这里显示 config.isbn 配置有误。

打开book.json,发现配置是这样:

  1. "isbn": null,

因为没有真实的ksbn,所以当时设置了null,这个用本地 gitbook 命令跑起来没有问题,但是 gitbook 官网的build就失败了。

解决方法:非常简单,删除这行,可以看到第二个build成功。

github webhook未添加

新书籍加入后,有时会报错(进书籍的 Settings),说github webhook未添加到这本书连接的 github 仓库:

方案4:混合 - 图6

此时点击左边的”Github”,再点”Manager Permissions”:

方案4:混合 - 图7

如果之前有设置github的 permission, 此时应该会立即显示 “Added” 字样:

方案4:混合 - 图8

再点回这本书籍的 Settings,就可以看到不再报错。

github组织不在列表中

gitbook的组织,必须要和github的组织对应上,才能使用。

在gitbook的组织管理页面中,在”github”页面进行管理时,有时会发现从”Select a Github organization”下拉框中找不到我们需要的github组织。

官方给出的解决方式如下:

打开下列地址:

https://github.com/settings/connections/applications/e103ee3796d447fab74c

选择对应的组织进行授权即可。