gitbook安装使用教程

4.5 周庆 Nginx 2018-12-26

GitBook 简介

GitBook 准备工作

熟悉`markdown`语法教程

安装 Node.js

GitBook 是一个基于 Node.js 的命令行工具,下载安装 Node.js,安装完成之后,您可以使用下面的命令来检验是否安装成功.

node -v

安装 GitBook

输入下面命令安装gitbook(二选一)

使用原始npm全局安装npm install gitbook-cli -g, -g参数代表全局安装
使用淘宝源安装gitbook(针对墙内用户)
1. 快速安装淘宝源npm,npm install -g cnpm --registry=https://registry.npm.taobao.org
2. cnpm install gitbook-cli -g,淘宝npm源在墙内安装速度会更快. 安装完成之后,使用gitbook -V来检测gitbook安装是否成功.

更多详情请参照 GitBook 安装文档

先睹为快

GitBook 准备工作做好之后,我们进入一个您要写书的目录,输入如下命令.

mkdir your_new_book
gitbook init

可以看到他会创建 README.md 和 SUMMARY.md 这两个文件,README.md 应该不陌生,就是说明文档,而 SUMMARY.md 其实就是书的章节目录,其默认内容如下所示：

接下来,我们输入 $ gitbook serve 命令,然后在浏览器地址栏中输入 http://localhost:4000 便可预览书籍.

效果如下所示：

运行该命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件. 我们可以使用下面命令来生成网页而不开启服务器.gitbook build 下面我们来详细介绍下 GitBook 目录结构及相关文件.

下面我们主要来讲讲 book.json 和 SUMMARY.md 文件.

book.json

该文件主要用来存放配置信息,我先放出我的配置文件.

    {
        "title": "标题",
        "author": "作者",
        "description": "描述简介",
        "language": "zh-hans",
        "gitbook": "3.2.3",
        "styles": {
            "website": "./styles/website.css"
        },
        "structure": {
            "readme": "README.md"
        },
        "links": {
            "sidebar": {
                "我的狗窝": "https://blankj.com"
            }
        },
        "plugins": [
            "-sharing",
            "splitter",
            "expandable-chapters-small",
            "anchors",

            "github",
            "github-buttons",
            "donate",
            "sharing-plus",
            "anchor-navigation-ex",
            "favicon"
        ],
        "pluginsConfig": {
            "github": {
                "url": "https://github.com/Blankj"
            },
            "github-buttons": {
                "buttons": [{
                    "user": "Blankj",
                    "repo": "glory",
                    "type": "star",
                    "size": "small",
                    "count": true
                    }
                ]
            },
            "donate": {
                "alipay": "./source/images/donate.png",
                "title": "",
                "button": "赞赏",
                "alipayText": " "
            },
            "sharing": {
                "douban": false,
                "facebook": false,
                "google": false,
                "hatenaBookmark": false,
                "instapaper": false,
                "line": false,
                "linkedin": false,
                "messenger": false,
                "pocket": false,
                "qq": false,
                "qzone": false,
                "stumbleupon": false,
                "twitter": false,
                "viber": false,
                "vk": false,
                "weibo": false,
                "whatsapp": false,
                "all": [
                    "google", "facebook", "weibo", "twitter",
                    "qq", "qzone", "linkedin", "pocket"
                ]
            },
            "anchor-navigation-ex": {
                "showLevel": false
            },
            "favicon":{
                "shortcut": "./source/images/favicon.jpg",
                "bookmark": "./source/images/favicon.jpg",
                "appleTouch": "./source/images/apple-touch-icon.jpg",
                "appleTouchMore": {
                    "120x120": "./source/images/apple-touch-icon.jpg",
                    "180x180": "./source/images/apple-touch-icon.jpg"
                }
            }
        }
    }

这个文件主要决定 GitBook 的章节目录,它通过 markdown 中的列表语法来表示文件的父子关系,下面是一个简单的示例：

    # Summary
    
    * [摘要](README.md)
    
    * [1. CMDB](chapter1/README.md)
      * [1.1 设备管理](chapter1/section1.1.md)
      * [1.2 业务管理](chapter1/section1.2.md)
    * [2. 软件管理](chapter2/README.md)
      * [2.1 软件仓库](chapter2/section2.1.md)
      * [2.3 自定义模板](chapter2/section2.2.md)
    * [3. 用户管理](chapter1/README.md)
      * [3.1 管理员](chapter3/section3.1.md)
      * [3.2 权限管理](chapter3/section3.2.md)
    * [4 .操作记录](chapter4/README.md)
      * [4.1 任务管理](chapter4/section4.1.md)

我们通过使用 标题 或者 水平分割线 将 GitBook 分为几个不同的部分,如下所示：

# Summary

### Part I

* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)

### Part II

* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

---

* [Last part without title](part3/title.md)

插件

gitbook 还支持许多插件,用户可以从 NPM 上搜索 gitbook 的插件,gitbook 文档推荐插件的命名方式为： gitbook-plugin-X: 插件 gitbook-theme-X: 主题

GitBook 有插件官网,默认带有 5 个插件,highlight,search,sharing,font-settings,livereload,如果要去除自带的插件, 可以在插件名称前面加 -,比如：

"plugins": [
    "-search"
]

如果要配置使用的插件可以在 book.json 文件中加入即可,比如我们添加 plugin-github,我们在 book.json 中加入配置如下即可：

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

然后在终端输入 gitbook install ./ 即可.

如果要指定插件的版本可以使用 plugin@0.3.1,因为一些插件可能不会随着 GitBook 版本的升级而升级.