Gitbook配置说明

写书,没那么复杂

看到像零基础学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语法,非常容易理解。以我参加“黑客写作课”时新建的目录为例:
1
2
3
4
5
6
7
8
9
10
# 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下是默认安装的)

    1
    $ node -v
  • 管理员权限安装gitbook:注意,一定要用管理员的权限进行安装

    1
    $ sudo npm install gitbook-cli -g
  • 检查版本:注意,检查版本是大写的V

    1
    $ gitbook -V
  • 启动服务:注意,一定要在对应的目录下启动服务

    1
    $ 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

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

ChangeLog

170106 新建