GitBook教程指南
工欲善其事必先利其器
前言
在V2EX上看到有讨论markdown工具的帖子，许多人推荐了Typora，简约美观。而我一直比较喜欢Gitbook。Gitbook有几个优点：
- 使用Git，方便存储、回退、协作等
- 轻松导出多种格式，如html、pdf等
- 有书籍列表，方便管理
- 有众多插件
安装
- 安装Node.js
- 安装gitbook
npm install -g gitbook-cli检查是否安装成功 gitbook -V
- 安装gitbook editor
进入官网下载安装，Mac也可以直接使用命令brew cask install gitbook-editor。
创建书籍
安装完环境以后，先试着创建一本书。先进入准备写书的目录，然后输入命令。
$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished这样就在当前目录创建了一本书。SUMMARY.md是书籍目录，README.md是书籍简介。 也可以指定目录创建书籍，如下。
gitbook init booknamebookname是书籍名，这样会先创建一个bookname的目录，然后再生成SUMMARY.md和README.md。
预览书籍
创建完书籍以后，一起来预览一下。在终端输入命令：
gitbook serve在浏览器中查看http://localhost:4000进行预览。
在书籍目录下，可以看到多了一个_book目录，里面就是网页的内容。
$ ls
README.md SUMMARY.md _book
$ ls _book
gitbook index.html search_index.json将_book推送到服务器，就是一个静态网站。
Github部署
- 先在Github创建一个书籍的工程
- 将本地工程推送到Github的工程，在书籍目录下输入命令：
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/PortgasAce/book.git
git push -u origin master将上面的url换成自己工程仓库即可，执行完后刷新Github可以看到本地的书籍被推送到远程。
- 使用Git Pages服务
GitPages是一个将github仓库作为网页展示的服务。使用它可以将书籍变为在线浏览。
启用GitPages服务有两个选项，一个是将master分支作为展示分支，另一个是将master分支的docs目录作为展示目录。
由于我们将书籍的markdown源文件推送到了master分支，所以选择docs目录作为GitPages服务的展示目录会更好。接下来，我们将之前产生在_book目录的文件生成到docs目录。进入书籍目录，输入命令
gitbook build . ./docs如果出现Error: ENOENT: no such file or directory, stat '/Users/portgas/Desktop/test/docs/gitbook/gitbook-plugin-sharing/buttons.js' 可以忽略。
然后推送到远程仓库，打开GitPages服务。
book.json的配置与个性化
模板
{
"author": "Portgas " ,
"description": "This is a sample book created by gitbook",
"extension": null,
"generator": "site",
"links": {
"sharing": {
"all": null,
"facebook": null,
"google": null,
"twitter": null,
"weibo": null
},
"sidebar": {
"100斤的博客": "http://blog.fiftykg.com"
}
},
"output": null,
"plugins": [],
"title": "Sample GitBook",
"variables": {}
}设置默认夜间模式
{
"pluginsConfig": {
"fontsettings": {
"theme": "night"
}
}
}插件
添加插件
在book.json plugins数据中添加即可，例如
"plugins": [
"sitemap"
]添加完成后，需要在书籍目录执行命令gitbook install .
删除自带插件
GitBook有插件官网，默认带有 5 个插件，highlight、search、sharing、font-settings、livereload，如果要去除自带的插件， 可以在插件名称前面加-，如：
"plugins": [
"-search"
]推荐插件
如果有好用的插件请推荐给我！
- 添加github图标：github
- 添加github star、fork github-buttons
- 侧边栏宽度调节 splitter
- 页脚 pagefooter
- google统计 GA
- 打赏 donate
- sitemap sitemap
- favicon favicon
SEO
- sitemap
- 待补充
常用命令汇总
gitbook init bookname创建书名为bookname的书gitbook serve本地预览gitbook build src dest编译src目录，生成到dest目录gitbook help查看命令帮助