2020/3/29 更新，新版现在已经挺好的用了，建议尝试

Gitbook 是很好的工具，虽然官网把它升级到 Gitbook/V2 的版本了，也没有很好的文档说明用法（我还不懂咋玩），所以现在用的都是旧版本的 Gitbook，网址自然就是 https://legacy.gitbook.com/
这儿推荐一个团队协同编辑的规范中文文案排版指北（简体中文版）。
本文的目的是推荐几个比较好用的插件以及聊聊我的 Gitbook 使用方法

介绍

GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书，GitBook 并非关于 Git 的教程。 –摘自《百度百科》

入门

入门这种东西我就不往这儿贴了，因为太多了。别人的教程写的更好，比较推荐大家去读一读 Gitbook 使用教程

插件推荐

在根目录的 book.json 下编辑即可，可以在 gitbook 项目的根目录使用 gitbook install ./ 来自动安装设置的插件

mathjax

地址： https://plugins.gitbook.com/plugin/mathjax

可以在 Markdown 中输入 Latex 公式
可以在网页上右键非常方便得显示出 MathML 格式的代码和 LaTeX 格式的代码。

splitter

地址： https://plugins.gitbook.com/plugin/splitter
提供了一个可以拖动的分割正文和目录的垂直条。

github-buttons

地址： https://plugins.gitbook.com/plugin/github-buttons
提供了一个非官方的github的star和fork等的显示，具体用法可以看文档

copy-code-button

地址： https://plugins.gitbook.com/plugin/copy-code-button
在代码段中添加一个copy按钮

search-plus

地址： https://plugins.gitbook.com/plugin/search-plus
更强大的一个搜索工具

expandable-chapters-small

地址： https://plugins.gitbook.com/plugin/expandable-chapters-small
让左侧的章节目录可以折叠

地址： https://plugins.gitbook.com/plugin/anchor-navigation-ex-toc
为文章增加锚点目录栏以及回到顶部等功能

在页面中增加 <extoc></extoc> 标签，会在此处生成TOC目录
在页面中增加  标签，不会在该页面生成悬浮导航

donate

地址： https://plugins.gitbook.com/plugin/donate
打赏插件，具体功能看文档

disqus

地址：https://plugins.gitbook.com/plugin/disqus
可以使用 disqus 插件来给 gitbook 加上评论功能（注意访问需要科学上网）
编辑 book.json，在 shortName 中填入你在 disqus 里面申请的 shortName

{
    "plugins": ["disqus"],
    "pluginsConfig": {
        "disqus": {
            "shortName": "XXXXXXX"
        }
    }
}

todo

地址： https://plugins.gitbook.com/plugin/todo
可以加入待办事项的显示
- [ ] 代办1
- [x] 已完成

gitHub

地址： https://plugins.gitbook.com/plugin/github
添加 GitHub 图标

"plugins": [
    "github"
],
"pluginsConfig": {
    "github": {
        "url": "https://github.com/zhangjikai"
    }
}

edit link

地址： https://plugins.gitbook.com/plugin/edit-link
如果你的仓库放在 GitHub 上面，可以链接到 GitHub 的修改页面
base 中比如我的就填 https://github.com/cugxuan/cugxuan.github.io/edit/master

"plugins": ["edit-link"],
"pluginsConfig": {
    "edit-link": {
        "base": "https://github.com/USER/REPO/edit/BRANCH",
        "label": "Edit This Page"
    }
}

book.json

放一个自用的 book.json

{
    "title" : "Gitbook Use",
    "author" : "Xuan",
    "language" : "zh-hans",
    "links" : {
        "sidebar" : {
            "Home" : "http://notes.cugxuan.cn"
        }
    },
    "plugins": [
        "mathjax",
        "splitter",
        "github-buttons",
        "copy-code-button",
        "-lunr",
        "-search",
        "search-plus",
        "expandable-chapters-small",
        "anchor-navigation-ex"
    ],
}

如何隐藏左下角的 Published with Gitbook

创建样式表文件“styles/website.css”，添加代码如下：

1
2
3

.gitbook-link {
    display: none !important;
}

编辑“book.json”文件，添加如下代码：

{
    "styles": {
        "website": "styles/website.css"
    }
}

如何部署

这里选择的是使用 github 进行部署，为此我写了一个脚本 deploy.sh
在 remote_url 中输入自己项目的地址，在 master 分支放自己的内容即可。

#!/bin/bash

# 设置远程仓库的地址
remote_url=git@github.com:PointStoneTeam/PointStone388.git
# 获取当前时间
cur_date="`date +%Y-%m-%d-%H:%M:%S`" 
# 生成_book文件
gitbook build

rm -rf .deploy_git/* | egrep .deploy_git/.git
if [ ! -d ".deploy_git/" ];then
	cp -R _book/ .deploy_git/
else
	cp -R _book/* .deploy_git/
fi
cd .deploy_git/
git init
git remote add origin $remote_url
git checkout -b gh-pages
git add -A
git commit -m $cur_date
git push -f origin gh-pages

如何使用 Deploy 脚本

需要环境

安装 nodejs 环境
安装 npm install gitbook-cli -g
执行 gitbook install ./
执行 gitbook serve
拥有仓库的推送权限

使用部署

将源文件更新到项目的 master 分支

1
2
3

$ git add -A
$ git commit -m "xx"
$ git push origin master

进行部署
1
2
3
$ ./deploy.sh
//如果没有权限，先给脚本以执行权限
$ chmod a+x deploy.sh
效果
在执行了 ./deploy.sh 之后，会自动在 github 的 gh-pages 分支上更新。
然后可以直接浏览网站查看效果 https://pointstoneteam.github.io/PointStone388/

如果网站不是使用的 Github Page 的方式进行的部署，而是放在服务器上面，可以参考一下我的另一篇文章

使用 webhook 自动更新博客

如何优雅地使用 Gitbook

介绍

入门