2019-03-14 如何优雅地使用Gitbook

http://blog.cugxuan.cn/2018/12/03/Markdown/How-to-use-gitbook-elegantly/

先扯几句有的没的，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目录
• 在页面中增加标签，不会在该页面生成悬浮导航

donate

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

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"
 ],
}

如何部署

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

#!/bin/bash

# 设置远程仓库的地址
[email protected]: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 分支

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

2. 进行部署

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

效果

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

参考资料

• 中文文案排版指北（简体中文版）
• Gitbook 官网
• Gitbook 使用教程