使用GitBook撰写书籍

正如你看到的，这本书就是使用gitbook撰写的

安装gitbook

  • 安装Node.js

参考 在 Windows、Mac OS X 與 Linux 中安裝 Node.js 網頁應用程式開發環境

我前期使用Hexo撰写blog，已经安装了node，使用以下命令验证

node -v

如果没有安装，可以使用nvm来管理node.js版本。注意：安装稳定版本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
nvm install stable

安装node.js之后，使用which node可以看到安装目录是用户目录下~/.nvm/versions/node/v8.6.0/bin/node

  • 安装Gitbook

使用NMP安装Gitbook - 参考 gitbllk-cli

npm install -g gitbook-cli

请使用nvm来安装node，这样可以在自己的用户目录下安装和管理各种版本node，就可以避免安装系统目录node，也就不需要使用sudo命令。

(不建议使用系统的node.js)如果使用系统范围的node.js，需要使用命令sudo npm install gitbook -g

安装完成后，使用以下命令验证是否安装成功，如果还没有安装gitbook（如前述只安装了gitbook-cli）则会自动安装稳定版本

gitbook -V

上述这个命令会安装稳定版本，如果要指定安装版本，例如安装alpha版本，则先检查可安装版本

然后安装pre版本

此时会看到gitbook被安装到$HOME/.gitbook/versions/4.0.0-alpha.4。并且，为了能够默认使用这个版本，还需要做一个软链接

此时再验证版本就会看到

显示输出使用了alpha版本，而不会去安装stable版本

升级Gitbook

检查已经安装的版本

查看远程版本

以上显示gitbook可安装版本，并且有Tag为latest稳定版本和pre的测试版本。

安装特定版本，例如安装alpha版本

安装预发布版本(根据gitbook ls-remote提示的版本标签)

升级最新稳定版本

如果要使用pre版本，则要使用

卸载稳定版本，准备改用pre版本

设置某个本地目录作为最新版本

上述命令实际上是在 $HOME/.gitbook/versions 目录下的多个gitbook版本，创建了一个软链接

如果要使用特定版本来build文档，可以使用

参考 Configuration 可以通过设置gitbook文档目录下的book.json文件配置来调整GitBook编译所使用的软件版本。例如，想使用最新的4.0.0-alpha.4，可以使用如下配置

这样使用命令gitbook build时候就不需要再增加--gitbook=4.0.0-alpha.4作为参数，简化命令。

不过，为了能够更加通用，实际我是在 $HOME/.gitbook/versions 执行以下命令，将4.0.0-alpha.4软链接成latest，这样后续所有执行gitbook就不需要再强制版本了（也不会再去下载latest版本）

此时再使用gitbook -V验证可以看到如下输出显示已经升级到最新的alpha版本

  • 将gitbook 3.2.2升级到4.0.0-beta版本后，还要注意，如果同时升级过node.js版本，需要在node.js中使用npm安装升级对应插件：

react react-dom react-disqus-thread gitbook-plugin-disqus这些npm包需要一起依赖安装，上述命令会全局安装到nvm目录下。

不过，最好还是在文档目录下编辑好book.json文件

然后执行以下命令先删除掉旧版本插件，然后重新安装插件

升级到4.0.0-alpha.4之后的处理

  • 在文档目录执行gitbook serve时候出现如下报错

解决方法参考常规的插件安装

提示gitbook-plugin-livereload是在/Users/huatai/.gitbook/versions/4.0.0-alpha.4目录（包含了packages.json配置文件），所以在这个执行npm i gitbook-plugin-livereload就会安装模块到该目录下的node_modules子目录中。这是npm的常规安装方法，并且这个本地安装方法会读取package.json文件来安装对应模块版本。 - 参考 Installing npm packages locally

但是，我发现上述本地安装gitbook-plugin-livereload模块实际上只在node_modules/gitbook-plugin-livereload更新了编译安装配置文件，实际上操作方法应该是进入node_modules/gitbook-plugin-livereload后执行npm install命令，所以再次修复

上述过程存在编译错误

参考 Error: Couldn't find preset “es2015” relative to directory “/Users/username” 先执行

但是报错依旧，另外发现./_assets/plugin.js文件内容是空的

尝试重新安装一次（重新安装前先全局安装一次 babel-cli babel-preset-es2015）

没有解决，暂时放弃尝试，回退到稳定版本

此时安装版本是稳定版本3.2.2

重新安装文档目录中的插件

  • 无法找到gitbook-core模块

还有报错

尝试再次安装gitbook-core模块

必须进入lib/node_modules/gitbook-cli才能执行上述安装命令，需要读取该目录下的package.json

  • TypeError: Cannot read property 'Page' of undefined

修复了gitbook-core模块问题后，又遇到不能读取Page属性问题

使用 gitbook -d serve 命令详细排查显示错误

显示报错和模块immutable有关

使用GitBook

  • 初始化目录cloud-atlas

我的个人"云图" cloud-atlas.huatai.me 记录自己在云计算领域的技术探索。

进入cloud-atlas.huatai.me目录可以看到该目录下有2个文件，除此之外什么也没有

  • 本地预览自动生成

编辑好初步的文档之后（例如编辑 README.md ）可以使用gitbook命令启用一个本地的服务进行预览

此时会在 cloudatlas 目录下生成一个子目录_book包含了所有生成的静态网站文件。

  • 使用build参数将静态文件生成到指定目录

也可以将静态文件生成到指定目录下，这样就可以方便打包输出的静态文件

通过浏览器访问 http://localhost:4000 来查看页面效果

输出pdf

要输出PDF文件，先安装gitbook-pdf

这里安装报错显示

参考Yeoman generator always get some error，尝试

虽然正确安装了 phantomjs-1.9.8，但是安装gitbook-pdf同样失败。后来发现，应该是这个安装 gitbook-pdf 依赖安装指定版本，所以参考 npm-install安装指定版本

还没有成功

GitBook简明使用手册

首页

详细的Gitbook使用参考 GitBook使用指南

默认文件README.md，这个文件是介绍网站的的说明，也是GitBook显示在首页的内容

在Gitbook的2.0.0之后，可以在 book.json 中指定文件作为README

章节

GitBook使用 SUMMARY.md来定义章节和子章节

子章节案例：

MarkDown

GitBook使用GitHub favorited markdown格式

  • 链接

    • 可以直接引用URL [Google官网](https://www.google.com)

    • 也可以引用本网站的文档，如 [内核进程状态参考](../../../../os/linux/kernel/process_stat_indicates.md)

    • 可以直接引用相同目录下的文档，如 [ssh portfording设置](ssh_portfording.md)：不过需要注意，所引用的文档必须在summary.md中已经定义，这样才能够创建html文件，并正确引用

    • 或者将超链接都集中到文档末尾（假如有多个相同的链接倒是比较方便，不过我没使用这个格式）

      [You can use numbers for reference-style link definitions][1]

    [1]: http://slashdot.org

发布

  • 首先在gitbook 注册一个账号

注册时候会发送一个确认邮件到你的邮箱，如果邮箱地址和你的gravatar注册头像一致，就会自动显示在gitbook上（也可以在设置中修改）。

  • 在gitbook的设置Profile中，其中有一项是Connect GitHub Account。使用这个管理功能，github会通过oauth方式，给予gitbook访问 公开的仓库 权限（这步需要么？）

  • 创建图书，在图书页面选择 github ，此时选择gitbub的某个公开的仓库（也就是你前面将自己的gitbook推送的仓库），通过关联后，这个仓库的书就会出现在在 https://{author}.gitbooks.io/{book}/

例如，我的有关云计算的书 Cloud Atlas https://huataihuang.gitbooks.io/cloud-atlas/

插件

gitbook插件可以给你的电子书带来更多的功能，请尝试吧！

GitBook + PlantUML 以 Markdown 快速製作 UML 教材

生成电子书

参考 Generating eBooks and PDFs

GitBook可以生成不同格式的电子书(ePub,Mobi,PDF)，需要安装一个 ebook-convert 组件(属于Calibre application，在Linux平台可以通过发行版安装)。

macOS可以安装Calibre application后用以下命令创建一个软链接：

  • 生成电子书

  • 电子书封面可以使用 autocover plugin创建，只需要提供两种大小的 cover.jpg 和 cover_small.jpg ，建议：

    • Size of 1800x2360 pixels for cover.jpg, 200x262 for cover_small.jpg

    • No border

    • Clearly visible book title

    • Any important text should be visible in the small version

升级

升级到GitBook 3.x 时候，在执行 gitbook serve 命令的终端提示

检查了 node_modules 目录下模块，发现是 gitbook-plugin-codeblock-filename 使用了 page.sections ，但是观察了最新的gitbook，发现已经支持章节缩进，所以就去除掉多个插件，只保留disqus插件。

发现访问 http://127.0.0.1:35729 不能正常展示，页面只提示

但是依然出现同样无法展示问题。参考 Gitbookのインストール（2016/1/19時点） ，原来这个页面{"tinylr":"Welcome","version":"0.2.1"}是表示安装gitbook成功。

但是，发现过了很久，大约 380 秒以后才提示出现

原来升级到新版本之后，在重新绘制页面出现了非常缓慢的问题。在 Generating slowly when the file number is large #1497 提出了同样的问题，显示升级到 3.x 之后build非常缓慢。我自己测试了一下，差不多一个文件需要1秒钟，期间单个CPU负载满负荷运行。

Setup and Installation of GitBook 提供了如下debug的方法

此外可以统计各阶段的使用时间

显示输出大部分时间消耗在template.render

回滚gitbook版本

参考 How do I install a previous version of an npm package?

上述方法并没有成功，我也尝试重新安装gitbook-cli，发现gitbook-cli安装的2.3.0版本自动安装了gitbook 3.2.2。所以暂时采用在更新了多个文档之后，只执行 gitbook build 生成静态文件，大多数情况下并不需要实时编译。

参考

PreviousGitBookNext如何在一台主机同时运行多个GitBook

Last updated

Was this helpful?