使用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常用命令
1
2
3
4
5
6
7
8
9
10
11
12
13
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 //输出错误信息

book.json 示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"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
  1. 想要尝试升级gitbook的版本,通过gitbook ls-remote查看可以安装的版本,然后利用gitbook fetch 4.0.0-alpha.6安装,尽管我用gitbook uninstall 3.2.3卸载了旧版本,安装之后不明白为何还是使用的3.2.3的稳定版本,后来用尝试创建软连接解决依然存在问题,没继续升级gitbook版本;
  2. 查看disqus-plugin文档没有解决,查看disqus项目issue,有人给出了答案,“1.0.1”版本需要gitbook的版本”>=4.0.0-alpha”,可以通过"plugins": ["disqus@0.1.0"]的方式,指定安装旧版本的disqus插键解决这个问题。

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

我们也可以通过@符号来指定插件的版本号,如:”plugins1@0.1.1“, 这个特性在使用一个旧版本的 gitbook 时是非常有用的

PS

npm安装指定版本:

1
npm install jquery@3.0.0

如果加上-g参数,表示安装到全局目录中

更新

  • 20200731:gitbook 已经该版本了,不支持上面介绍的这种方式了,登录他们官网可以查看如何使用。

参考

Michael翔 wechat
ヾノ≧∀≦)o 欢迎订阅公众号「Coder魔法院」☑工具控 ☑编程 ☑读书☑电影
「🤓 码字不易,赏个茶叶蛋 👇」