使用GitBook+Github编写文档书籍

Books are to mankind what memory is to the individuanl. 书之于人类，犹如记忆于之个人。

最近看到了python-web-guide这样的文档以及explore python，觉得知识体系还是用这种方式全面组织比较系统一点，因此，放假在家也搞一下gitbook吧！

欢迎访问我的第一本GitBook-HackPythonista，目前内容有待丰富，囧

鉴于已有相当多的文档介绍了Git，本文仅做简要笔记，同时记录一下遇到的坑。

gitbook基本使用

全局安装 gitbook

1	sudo npm install gitbook-cli -g

安装完成，执行gitbook -V查看版本信息；

gitbook常用命令

gitbook init //初始化目录文件
gitbook help //列出gitbook所有的命令
gitbook --help //输出gitbook-cli的帮助信息
gitbook build //生成静态网页
gitbook serve //生成静态网页并运行服务器
gitbook build --gitbook=2.0.1 //生成时指定gitbook的版本, 本地没有会先下载
gitbook ls //列出本地所有的gitbook版本
gitbook ls-remote //列出远程可用的gitbook版本
gitbook fetch 标签/版本号 //安装对应的gitbook版本
gitbook update //更新到gitbook的最新版本
gitbook uninstall 2.0.1 //卸载对应的gitbook版本
gitbook build --log=debug //指定log的级别
gitbook builid --debug //输出错误信息

与github集成，参考文章chengweiBlog-GitHub 集成
安装gitbook插键，参考文章chengweiBlog-book.json
在书籍根目录创建book.json。

book.json 示例：

{
  "gitbook": "3.2.3",
  "language": "zh",
  "description": "Michael翔技术栈NoteBook",
  "plugins": [
    "disqus@0.1.0",
    "anchor-navigation-ex",
    "-lunr",
    "-search",
    "search-pro-kui"
  ],
  "pluginsConfig": {
    "disqus": {
      "shortName": "HackPythonista"
    },
    "anchor-navigation-ex": {
      "isShowTocTitleIcon": true,
      "tocLevel1Icon": "fa fa-hand-o-right",
      "tocLevel2Icon": "fa fa-hand-o-right",
      "tocLevel3Icon": "fa fa-hand-o-right"
    }
  }
}

gitbook插键

disqus插键

按照前面参考文章安装disqus插键时，使用命令npm install gitbook-plugin-disqus会默认安装disqus的最新版本，然后gitbook serve时，就会报错：

1
2
3

info: loading plugin "disqus"... ERROR

Error: GitBook doesn't satisfy the requirements of this plugin: >=4.0.0-alpha

想要尝试升级gitbook的版本，通过gitbook ls-remote查看可以安装的版本，然后利用gitbook fetch 4.0.0-alpha.6安装，尽管我用gitbook uninstall 3.2.3卸载了旧版本，安装之后不明白为何还是使用的3.2.3的稳定版本，后来用尝试创建软连接解决依然存在问题，没继续升级gitbook版本；
查看disqus-plugin文档没有解决，查看disqus项目issue，有人给出了答案，“1.0.1”版本需要gitbook的版本”>=4.0.0-alpha”，可以通过"plugins": ["disqus@0.1.0"]的方式，指定安装旧版本的disqus插键解决这个问题。

后来看到disqus插键官网文档，发现明明有写这些的，自己没注意到，文档多重要.