写书，没那么复杂

看到像零基础学Python，（原作者的内容零基础学Python）或者用Python学微积分这样的（原仓库）的内容和呈现都很简洁实用的内容时，不知道你会不会像我一样，产生写点什么的冲动。Gitbook无疑是非常适合入门的写书工具了，想用Geek的方式，CLI完成本地环境和远程部署，或者简单的下载客户端写书上传，一切如你所愿。 新建Gitbook的方法很多，注册账号后，直接在网页端点击 +New Book，会出现六个选项，在这里重点推荐第五种GITHUB-Import and sync an existing GitHub repository.直接导入一个已经存在的Github仓库的方式。好处是Gitbook直接和Github关联，只要了解清楚Gitbook实现原理，剩下的一切都按照Github的方式进行协同，Gitbook会自动同步，最终的效果是你只关注在自己的内容中，gitbook像一个忠实的后台进程，默默的完成了其他所有事项。

信息的源头

在前面的博客里经常提到查看官方文档的重要性，这里也不例外，在Gitbook主页下方提供了一排链接，花三分钟看一下，后面的操作一目了然。

“About Help Explore Editor Blog Pricing Contact”

Gitbook也是一个开源项目，可以直接通过上面的链接找到源码。GitBook Help CenterExplore可以探索收藏最多的电子书，通过标签搜索会更精准。Blog更是展示了Gitbook的发展轨迹。

回到GitBook Help Center，如果不满足于官方提供的默认模版，请继续“折腾”吧，你一定会发现下面的这些内容:

看的文档越多，问题也会越多：什么是主题、什么是插件、如何定制CSS、为什么是Toolchain等等。恭喜你，找到了问题就找到了动机，继续探索下去一定会重新认识Gitbook这个工具。那么这篇博客到此也就结束了。

后面的内容主要是自己在“折腾”过程中的一些记录，可以作为入门者的参考。

更新方法

我的Gitbook都会连接到Github，降低事情的复杂度。“Modern documentation format and toolchain using Git and Markdown”，让Gitbook关注在格式方法和功能上，而文档的管理放到github。更新主要有三种方法：

  • Github本地仓库更新目录和文章内容：更新后和Github的仓库更新方法一样远程更新。
  • Gitbook网页寻找合适的插件和文档的配置：在网页做基本的文档Settings配置和插件的更新配置。
  • 电脑客户端更新目录和文章内容（不推荐），用CLI和Github已经习惯，不再赘述。

文件结构与同步机制

Gitbook的文件结构主要有三部分组成：目录文件、内容文件、其他文件。目录文件和内容文件的路径要相互呼应。根目录下的 README.md 文件是整个电子书的简介，点击进入电子书时展示。

  • 目录文件：在根目录下的“SUMMARY.md”文件里是整个电子书的目录结构，文件的内容均是符合Markdown语法，非常容易理解。以我参加“黑客写作课”时新建的目录为例：
# Summary

* [Introduction](README.md)
* [Git & GitHub](1Git&GitHub/README.md)
* [Markdown](2Markdown/README.md)
* [Jekyll](3Jekyll/README.md)
* [OS & Search](4OS&Search/README.md)
* [Command Line Interface](5CLI/README.md)
* [GitBook](6Gitbook/README.md)
* [About](About.md)
  • 内容文件：内容文件均是符合Markdown语法，如果有需要，可以建立多个文件夹，只要像上面的代码一样设置好对应的路径，在电子书中就能正常展示了。
  • 其他文件：更新了插件的信息后，会自动生成book.json等文件，如果自定义的主题还会有CSS等相关文件，统称为“其他文件”。
  • 同步机制：插件的内容会在Gitbook的网页端更新，网页端如果修改了文件可以直接可视化，不用担心Gitbook的文件是否还需要同步。因为这两个网站都是遵循Git的版本管理，在gitbook更新的内容提交后，会自动同步到github中。

优秀插件

Gitbook中有许多优秀的插件，对电子书进行功能增强，比如添加评论功能等,可以在plugin store找到。在网页端的编辑页面点击右侧的箭头，可以打开插件商店，选择自己需要的插件按照要求安装即可。

插件的生效与失效

  • 方法一：在plugin store中直接启动插件，然后。在本地的文件book.json做一个简单的配置即可。
  • 方法二：网上部分文章都在说插件需要配置本地环境云云。其实可以直接网页端生效（下面细说）。另外，gitbook的本地环境搭建有一些困难。不知道是因为网络还是因为GFW，PC、MAC总是安装失败。所以这个方法就不多说了，有兴趣的小伙伴可以自己去搜索。
  • 插件失效方法：
    1. 在book.json中对应插件名称的前面加一个短横线即可
    2. 直接在plugin store中选择这个插件并关闭，其实代码也是会和1.中提到的一样，不过是系统自动执行的操作。

增加多说评论工具

  1. 先找到插件的内容，查看相关说明
  2. 在plugin store中找到多说，选择开启
  3. 在多说注册short_name
  4. 在book.json中把1中提到的代码粘贴过去，并且修改short_name
  5. 保存文档，正常就可以使用了

了解更多的插件

还有不明白的地方，可以参考GitBook插件（Github仓库）和他的其他文章，或者这里。

本地环境搭建

Gitbook的本地安装很有必要，不再需要把文件上传到服务器就能看到效果，缩短调试的周期。我尝试了PC和MAC的安装，结果MAC比较顺利，PC还没有成功，后续继续尝试。

MAC安装

  • 检查是否已经安装了Node：如果已经安装，继续；如果没有，还需要安装。（不过好像MAC下是默认安装的）
$ node -v
  • 管理员权限安装gitbook：注意，一定要用管理员的权限进行安装
$ sudo npm install gitbook-cli -g
  • 检查版本：注意，检查版本是大写的V
$ gitbook -V
  • 启动服务：注意，一定要在对应的目录下启动服务
$ gitbook serve

PC安装

安装步骤

  1. 安装nodejs，在node官网下载nodejs（nodejs.org/en/ ），安装。
  2. 在命令行中输入命令： node -v
  3. 输入命令，全局安装gitbook：npm install gitbook-cli -g

问题处理

错误1

执行代码：$ npm install gitbook-cli -g之后会显示如下错误

npm ERR! Windows_NT 6.1.7601 npm ERR! argv “C:\Program Files\nodejs\node.exe” “C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js” “install” “gitbook-cli” “-g” npm ERR! node v4.4.7 npm ERR! npm v2.15.8 npm ERR! shasum check failed for C:\Users\Leonwang\AppData\Local\Temp\npm-4500-f6cc2e13\registry.npmjs.org\npm-\npm-3.7.5.tgz npm ERR! Expected: a7dae58e52ecbe263c1c860c6fd64ffa50f3c79b npm ERR! Actual: 4a8a44d5be01a7cbc3b97dc09a94013db04b4b9a npm ERR! From: https://registry.npmjs.org/npm/-/npm-3.7.5.tgz npm ERR! npm ERR! If you need help, you may report this error at: npm ERR! https://github.com/npm/npm/issues npm ERR! Please include the following file with any support request: npm ERR! C:\Users\Leonwang\Desktop!Github\wangjunyu.github.io\npm-debug.log

处理办法：还没有找到更好的办法。问题相关,相关1

本地环境启动时注意事项

前提：在服务器端设置完成，多说可以正常使用。 如果要在本地启动某个文件的电子书服务，会出现报错要求本地安装插件，只要运行代码： $ gitbook install，然后再执行gitbook serve。

[完](http://blog.junyu.pro)

声明: 本文转载需标明出处，禁止用于商业目的。

ChangeLog

170106 新建