1 安装gitbook

npm i gitbook-cli -g

2 初始化gitbook项目

新建一个项目目录，终端执行以下命令

gitbook init

初始化过程遇到以下问题。

问题1：

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

检查了一下，本地没有安装Xcode，可以在appstore中，搜索xcode安装。

问题2：

TypeError: cb.apply is not a function

详细错误如下：

/data/soft/nodejs/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
      if (cb) cb.apply(this, arguments)

TypeError: cb.apply is not a function
    at /data/soft/nodejs/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (fs.js:169:5)

打开polyfills.js文件，找到这个函数

function statFix (orig) {
  if (!orig) return orig
  // Older versions of Node erroneously returned signed integers for
  // uid + gid.
  return function (target, cb) {
    return orig.call(fs, target, function (er, stats) {
      if (!stats) return cb.apply(this, arguments)
      if (stats.uid < 0) stats.uid += 0x100000000
      if (stats.gid < 0) stats.gid += 0x100000000
      if (cb) cb.apply(this, arguments)
    })
  }
}

在第62-64行调用了这个函数

// fs.stat = statFix(fs.stat)
// fs.fstat = statFix(fs.fstat)
// fs.lstat = statFix(fs.lstat)

把这三行代码注释掉就解决报错了。

注释掉之后，重新执行初始化，成功创建项目。

初始化完成后，在执行目录中生成README.md 和 SUMMARY.md 两个文件。

3 打包GitBook项目

gitbook build

本地构建不运行服务。

打包完成后，打包文件默认输出到 _book/目录，在项目根目录中。

4 运行GitBook服务

gitbook serve

本地构建运行服务。

执行后，可通过浏览器访问 http://localhost:4000 实时预览。

5 GitBook常用命令

• 安装 GitBook：npm i gitbook-cli -g
• 初始化 GitBook 项目：gitbook init
• 安装 GitBook 依赖：gitbook install
• 开启 GitBook 服务：gitbook serve
• 打包 GitBook 项目：gitbook build
• GitBook 命令行查看：gitbook -help
• GitBook 版本查看：gitbook -V

6 GitBook目录结构

- GitBook
    _book
    - README.md
    - SUMMARY.md
    - book.json
    - GLOSSARY.md
    - LANGS.md

README.md 是默认首页文件，相当于网站的首页 index.html ,一般是介绍文字或相关导航链接.

SUMMARY.md 是默认概括文件，主要是根据该文件内容生成相应的目录结构，同 README.md 一样都是被 gitbook init 初始化默认创建的重要文件.

_book 是默认的输出目录，存放着原始 markdown 渲染完毕后的 html 文件，可以直接打包到服务器充当静态网站使用。一般是执行 gitbook build 或 gitbook serve 自动生成的.

book.json 是配置文件，用于个性化调整 gitbook 的相关配置，如定义电子书的标题、封面、作者等信息。虽然是手动创建但一般是必选的.

GLOSSARY.md 是默认的词汇表，主要说明专业词汇的详细解释，这样阅读到专业词汇时就会有相应提示信息，也是手动创建但是可选的.

LANGS.md 是默认的语言文件，用于国际化版本翻译和 GLOSSARY.md 一样是手动创建但是可选的.

7 book.json配置文件说明

title：网站标题

author：网站作者

description：网站功能描述

language：网站使用语言

styles：网站额外配置的样式表

plugins：网站使用的插件

pluginsConfig：网站使用的插件的额外配

示例：

{
"title": "这里是标题",
"author": "这里是作者",
"description": "这里是描述",
"language": "zh-hans",
"plugins": [
            "-highlight",
            "copy-code-button",
            "search-pro",
            "-search",
            "-lunr",
            "expandable-chapters",
            "splitter",
            "-sharing",
            "github-buttons",
            "donate",
            "tbfed-pagefooter",
            "baidu-tongji",
            "anchor-navigation-ex"
          ],
"pluginsConfig": {
        "github-buttons": {
                "buttons": [
                        {
                            "user": "username",
                            "repo": "blog",
                            "type": "star",
                            "count": true,
                            "size": "small"
                        },
                        {
                            "user": "username",
                            "width": "160",
                            "type": "follow",
                            "count": true,
                            "size": "small"
                        }
                   ]
              },
        "donate": {
                "button": "打赏",
                "wechatText": "微信打赏",
                "wechat": "***.jpg"
                },
        "tbfed-pagefooter": {
                "copyright":"Copyright Description",
                "modify_label": "该文件修订时间：",
                "modify_format": "YYYY-MM-DD HH:mm:ss"
                },
        "baidu-tongji": {
                "token": "XXXXX"
                },
        "anchor-navigation-ex": {
                "showLevel": false
                }
        }
}

待续：

GitBook支持构建多语言文档，实现站点国际化

GitBook安装评论插件，实现可留言的文档系统