Gitbook-Cli Tutorial

A User Guide of Gitbook-cli.

gitbook-cli是一个基于Node.js的命令行工具。

Install

# install node.js 10.23.1 and npm
curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt-get install -y nodejs
​
# check the node.js version
nodejs -v
​
# install gitbook
sudo npm install -g gitbook-cli
​
# check the gitbook version
gitbook -V

Usage

Basic command

• 新建书籍，在目录中执行：gitbook init

• 构建预览html文件：gitbook build

• 开启服务在浏览其中预览：gitbook serve

Directory structure

在初始化之后将获得两个文件README.md和SUMMARY.md

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

• book.json：主要用来放置配置信息，包括页面设置，插件等。

• README.md：通常是gitbook的说明信息

• SUMMARY.md：决定 GitBook 的章节目录，它通过 Markdown 中的列表语法来表示文件的父子关系，下面是一个简单的示例。

# SUMMARY.md
* [Introduction](README.md)
* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)

这个配置对应的目录结构如下所示:

Gitbook-plugin

GitBook 有 插件官网，默认带有 5 个插件，highlight、search、sharing、font-settings、livereload。修改gitbook-plugin只需要修改项目目录下的book.json即可，例如：

{
    "plugins": [
        "toc",
        "hide-element",
        "page-treeview",
        "simple-page-toc"
    ],
​
    "pluginsConfig":{
        "hide-element": {
            "elements": [".gitbook-link"]
        },
        "page-treeview": {
            "copyright": "Copyright © aleen42",
            "minHeaderCount": "2",
            "minHeaderDeep": "6"
        }
    }
​
}

• toc为目录插件

• hide-element为隐藏组件插件，用于隐藏gitbook Copyright

• page-treeview目录插件

• simple-page-toc简易导航插件

• gitbook install安装新插件

Markdown

Gitbook文档使用.md格式文档，关于Markdown的语法可以查看Markdown教程。

Markdown编辑器可以使用Typora.

FAQ

禁用page-treeview plugin copyright

Copyright信息为plugin作者内嵌信息，需要修改plugin脚本源码，删除关于copyright相关定义与显示。

# 当前项目目录
vim ./node_modules/gitbook-plugin-page-treeview/lib/index.js
​
# 查找Copyright相关定义，删去即可
# 注意：每次执行gitbook install之后都要修改

gitbook build生成的.html单击不跳转：

点击事件被js代码禁用导致新版本的gitbook不支持单击事件，所以点击没有反应，但是如果右键，在新窗口/新标签页打开的话是可以跳转的，解决办法如下：

# 当前项目目录
vim ./_book/gitbok/theme.js
​
# 查找 “if(m)for(n.handler&&“
# 将判断条件m改为false即可
# 注意：每次gitbook build之后都需要修改

gitbook部署

# 将远端仓库克隆到本地
# 然后将本地修改上传，并使用Github Pages来解析
git push -u origin master
git subtree push --prefix=_book origin gh-pages