gitbook安装与使用（含常用插件和book.json配置详解）

本文是我的个人网站G笔记中的内容，最新的内容可访问G笔记

GitBook 安装教程

下面将介绍本地如何安装GitBook

环境要求

node版本要求：V4.0.0以上

通过npm安装

执行命令：

npm install gitbook-cli -g

通过gitbook -V命令查看是否安装成功。

初始化

新建一个文件夹，例如新建 mygitbook ，然后在该目录下执行命令：

gitbook init

会自动生成两个必要的文件 README.md 和 SUMMARY.md。

预览

执行命令：

gitbook serve

gitbook会启动一个4000端口用于预览，可以在浏览器打开网址： http://localhost:4000 预览效果。

编译

执行命令：

gitbook build

运行该命令后会在根文件夹生成一个 _book 文件夹，包含了书籍的所有 html 文件. 可以使用该命令来生成网页而不开启服务器，也可以将_book文件夹部署到服务器上。

---

GitBook 命令

这里将介绍GitBook的一些命令

输出gitbook的帮助信息

gitbook --help

生成静态网页并运行服务器

gitbook serve

生成静态网页

gitbook build

生成静态网页时指定gitbook的版本，如果本地没有将先下载

gitbook build --gitbook=3.2.3

列出所有的gitbook版本

gitbook ls

列出远程可用的gitbook版本

gitbook ls-remote

更新到gitbook的最新版本

gitbook update

卸载对应的gitbook版本

gitbook uninstall 3.2.3

安装依赖

gitbook install

指定log的级别

gitbook build --log=debug

输出错误信息

gitbook builid --debug

---

GitBook book.json 配置

title 设置书本的标题

“title” : “私人笔记”

author 作者的相关信息

“author” : “lijiam”

description 本书的简单描述

“description” : “lijiam的私人笔记”

language Gitbook使用的语言

“language” : “zh-hans”

版本2.6.4中可选的语言如下：

en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

links 在左侧导航栏添加链接信息

"links" : {
    "sidebar" : {
        "Personal Book" : "http://www.gtwteam.com"
    }
}

styles 自定义页面样式

默认情况下各generator对应的css文件

"styles": {
    "website": "styles/website.css",
    "ebook": "styles/ebook.css",
    "pdf": "styles/pdf.css",
    "mobi": "styles/mobi.css",
    "epub": "styles/epub.css"
}

例如使h1 h2标签有下划线， 可以在website.css中设置

h1 , h2{
    border-bottom: 1px solid #EEEEEE;
}

plugins 插件列表

可以在插件前面加-符号删除默认插件，默认五种插件如下，更多插件

• highlight：代码高亮
• search：导航栏查询功能（不支持中文）
• sharing：右上角分享功能
• font-settings：字体设置（最上方的"A"符号）
• livereload：为GitBook实时重新加载

pluginsConfig 配置插件的属性

---

GitBook 插件

这里将记录一些实用的插件，安装是可以指定版本，如：[email protected]。下面列举的插件是V3.2.3版本的GitBook下测试通过可用的，因为有些插件可能很久没升级，不会随着GitBook版本升级，所以使用插件未生效或报错时要注意GitBook版本。

插件列表

• back-to-top-button（返回顶部）
• code（代码添加行号&复制按钮）
• search-pro（高级搜索，支持中文）
• github（在右上角添加github图标）
• splitter（侧边栏宽度可调节）
• tbfed-pagefooter（页面添加页脚，简单的）
• page-copyright（页面页脚版权，复杂的）
• donate（打赏插件）
• sharing-plus（分享当前页面）
• custom-favicon（修改标题栏图标）
• prism（代码高亮）
• todo（复选框）
• pageview-count（阅读量计数）
• auto-scroll-table（表格滚动条）
• image-captions（显示图片名称）
• styles-sass（使用sass替换css）
• styles-less（使用less替换css）
• toggle-chapters（目录折叠）
• multipart（分章节展示）
• 其他：设置导航序号

如何添加插件？

在book.json中配置如下（这里用code插件作为例子）：

{
    "plugins": [
        "code"
    ],
    "pluginsConfig": {
        "code": {
            "copyButtons": false
        }
    }
}

然后通过以下三种方式中的一种进行安装：

• 执行gitbook install
• 使用npm安装，命令格式npm install gitbook-plugin-插件名字，如npm install gitbook-plugin-code
• 从GitHub下载源码，放到node_modules文件夹里。

---

back-to-top-button（返回顶部）

插件地址

code（代码添加行号&复制按钮）

插件地址

插件配置：去掉复制按钮，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
      "code": {
        "copyButtons": false
      }
    }
}

search-pro（高级搜索，支持中文）

插件地址

github（在右上角添加github图标）

插件地址

插件配置：设置GitHub地址，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/lijiam"
        }
    }
}

splitter（侧边栏宽度可调节）

插件地址

tbfed-pagefooter（页面添加页脚，简单的）

插件地址

配置，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright":"Copyright © lijiam 2019",
            "modify_label": "本书发布时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

page-copyright（页面页脚版权，复杂的）

插件地址

配置，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
        "page-copyright": {
          "description": "modified at",
          "signature": "你的签名",
          "wisdom": "Designer, Frontend Developer & overall web enthusiast",
          "format": "YYYY-MM-dd hh:mm:ss",
          "copyright": "Copyright © 你的名字",
          "timeColor": "#666",
          "copyrightColor": "#666",
          "utcOffset": "8",
          "style": "normal",
          "noPowered": false,
        }
    }
}

donate（打赏插件）

插件地址

配置，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
        "donate": {
            "wechat": "微信收款的二维码URL",
            "alipay": "支付宝收款的二维码URL",
            "title": "",
            "button": "赏",
            "alipayText": "支付宝打赏",
            "wechatText": "微信打赏"
        }
    }
}

sharing-plus（分享当前页面）

比默认的 sharing 插件多了一些分享方式。插件地址

配置，可以在book.json的pluginsConfig中添加如下（需要将默认的sharing删掉）：

{
    "plugins": ["-sharing", "sharing-plus"],
    "pluginsConfig": {
        "sharing": {
            "facebook": true,
            "twitter": true,
            "weibo": true,
            "qq": true,
        "all": [
            "douban", "google", "instapaper", "linkedin", "twitter", "messenger", "qzone", "viber", "whatsapp"
           ]
       }
    }
}

其中：为true的代表直接显示在页面顶端，为false的不显示，不写默认为false，"all"中代表点击分享符号显示出来的，支持网站：

    "douban", "facebook", "google", "hatenaBookmark", 
    "instapaper", "linkedin","twitter", "weibo", 
    "messenger","qq", "qzone","viber","vk","weibo",
    "pocket", "stumbleupon","whatsapp"

custom-favicon（修改标题栏图标）

插件地址

配置，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
        "favicon": "images/favicon.ico"
    }
}

prism（代码高亮）

插件地址

配置，可以在book.json的pluginsConfig中添加如下（主题色css详见官网）：

{
    "plugins": ["prism", "-highlight"],
    "pluginsConfig": {
        "prism": {
            "css": [
                "prismjs/themes/prism-okaidia.css"
            ],
            "lang": {
                "flow": "typescript"
            }
        }
    }
}

todo（复选框）

插件地址

使用示例：

* [ ] 这是一个未选中的
* [x] 这是一个已选中的

pageview-count（阅读量计数）

插件地址

这里可能需要改下源代码，在node_modules中找到gitbook-plugin-pageview-count插件，然后找到assets下的plugins.js，按照下面的改法调整代码（我装的时候在第25行）：

// 未调整前
var fontSize = bookHeader.find('.dropdown');
// 调整后
var fontSize = bookHeader.find('.font-settings');

auto-scroll-table（表格滚动条）

为避免表格过宽，增加滚动条。插件地址

image-captions（显示图片名称）

抓取内容中图片的 alt 或 title 属性，在图片下面显示标题。插件地址

配置，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
        "image-captions": {
          "caption": "Image _PAGE_LEVEL_._PAGE_IMAGE_NUMBER_ - _CAPTION_"
      }
    }
}

styles-sass（使用sass替换css）

插件地址

配置，可以在book.json的pluginsConfig中添加如下：

{
    "plugins": ["styles-sass"],
    "styles": {
        "pdf": "styles/pdf.sass"
    }
}

styles-less（使用less替换css）

插件地址

配置，可以在book.json的pluginsConfig中添加如下：

{
    "plugins": ["styles-less"],
    "styles": {
        "pdf": "styles/pdf.less"
    }
}

toggle-chapters（目录折叠）

插件地址

multipart（分章节展示）

插件地址

SUMMARY.md例子：

# GitBook

## 第一章
* [第一节](part1/1/README.md)
    * [1.1](part1/1.1/README.md)
* [第二节](part1/2/README.md)
* [第三节](part1/3/README.md)

## 第二章
* [第一节](part2/1/README.md)

## 第三章

其他：设置导航序号

配置，可以在book.json的pluginsConfig中添加如下：

{
    "pluginsConfig": {
        "theme-default": {
            "showLevel": true
        }
    }
}

---

book.json配置

{
    "title": "G笔记",
    "description": "好记性不如G笔记",
    "author": "lijiam",
    "output.name": "site",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "root": ".",
    "links": {
        "sidebar": {
            "首页": "http://www.lijiam.com"
        }
    },
    "plugins": [
        "code",
        "-search",
        "search-pro",
        "github",
        "splitter",
        "tbfed-pagefooter",
        "donate",
        "-sharing",
        "sharing-plus",
        "prism",
        "-highlight",
        "styles-less",
        "toggle-chapters",
        "multipart",
        "ancre-navigation"
    ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/lijiam"
        },
        "code": {
            "copyButtons": true
        },
        "tbfed-pagefooter": {
            "copyright": "Copyright © lijiam 2019",
            "modify_label": "本书发布时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        },
        "donate": {
            "wechat": "/assets/images/wxpay.png",
            "alipay": "/assets/images/alipay.png",
            "title": "",
            "button": "赏",
            "alipayText": "支付宝打赏",
            "wechatText": "微信打赏"
        },
        "sharing": {
            "facebook": true,
            "twitter": true,
            "weibo": true,
            "qq": true,
            "all": [
                "douban",
                "google",
                "qzone",
                "linkedin"
            ]
        },
        "prism": {
            "css": [
                "prismjs/themes/prism-solarizedlight.css"
            ],
            "lang": {
                "flow": "typescript"
            }
        }
    },
    "styles": {
        "website": "assets/styles/website.less",
        "ebook": "assets/styles/ebook.less",
        "pdf": "assets/styles/pdf.less",
        "mobi": "assets/styles/mobi.less",
        "epub": "assets/styles/epub.less"
    }
}