如何优雅地使用Gitbook

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

介绍

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

入门

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

插件推荐

在根目录的 book.json 下编辑即可,可以使用 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
更强大的一个搜索工具

anchor-navigation-ex-toc

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

  • 在页面中增加标签,会在此处生成TOC目录
  • 在页面中增加标签,不会在该页面生成悬浮导航

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

book.json

放一个自用的 book.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"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"
],
}

如何部署

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
#!/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
  • 拥有仓库的推送权限

使用部署

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

    1
    2
    3
    $ git add -A
    $ git commit -m "xx"
    $ git push origin master
  2. 进行部署

    1
    2
    3
    $ ./deploy.sh
    //如果没有权限,先给脚本以执行权限
    $ chmod a+x deploy.sh

效果

在执行了 ./deploy.sh 之后,会自动在 githubgh-pages 分支上更新。
然后可以直接浏览网站查看效果 https://pointstoneteam.github.io/PointStone388/

参考资料

如果对您有帮助,请我喝杯咖啡?