Gitbook的实用技巧专栏

时间 2019-11-16

标签 gitbook 实用技巧专栏栏目 Git 繁體版

原文原文链接

专栏目录

专栏详情

Gitbook

Gitbook介绍

GitBook 是一个基于 Node.js 的命令行工具
可用 Github/Git 和 Markdown 组合制做成精美的电子文档
GitBook支持输出多种文档格式：
    * 静态站点: GitBook默认输出格式, 生成的静态站点
    * PDF: 须要安装 gitbook-pdf
    * eBook: 须要安装ebook-convert
    * 单HTML网页: 支持将内容输出为单页HTML, 不过通常用在将电子书格式转换为PDF或eBook的中间过程
    * JSON: 通常用于电子书的调试或元数据提取
使用GitBook制做电子书, 必备两个文件: README.md[主页面] SUMMARY.md[侧边栏页面]
复制代码

Gitbook安装

# 安装Gitbook须要node.js做为前提依赖, 安装时确保主机已经存在node.js
node -v

# 安装Gitbook多版本托管工具, 可同时托管多个Gitbook版本, 且下载最新版的Gitbook驱动
npm install gitbook-cli -g

# 验证下载是否成功
gitbook -V

# 下载历史版本[下载3.0.0版本]
# 3.2.3版本确保为不可用版本, 推荐使用3.0.0
gitbook fetch 3.0.0

# 进入到你的项目文件夹, 初始化一个Gitbook项目
gitbook init

# 生成README.md 和 SUMMARY.md 两个基本文件

# 启动服务
gitbook serve

# 指定gitbook版本启动
gitbook serve --gitbook=3.0.0

# 获取帮助
gitbook --help

# 卸载指定版本Gitbook[卸载3.2.3版本]
gitbook uninstall 3.2.3

# 生成静态网页
gitbook build

# 指定gitbook版本生成静态文件，若是本地没有将先下载
gitbook build --gitbook=3.0.0

# 列出本地全部的gitbook版本
gitbook ls

# 列出远程可用的gitbook版本
gitbook ls-remote

# 更新到gitbook的最新版本
gitbook update

# 安装配置依赖插件
gitbook install

# 指定log的级别
gitbook build --log=debug

# 输出错误信息
gitbook builid --debug
复制代码

Gitbook简单使用

在 README.md 中撰写Gitbook项目的主界面, 而 SUMMARY.md 是Gitbook界面中侧边栏的属性
README.md示例node

# 主界面简介
------
此文档的简单描述

### 目录介绍
* [目录1](1.md)
* [目录2](2.md)
* [目录3](2.md)
* [目录4](4.md)
复制代码

SUMMARY.md示例git

* [目录1](1.md)
* [目录2](2.md)
* [目录3](2.md)
* [目录4](4.md)
复制代码

项目根目录下能够建立 book.json 实现全局配置文件信息github

{
    "title": "MedusaSorcerer的博客文档",
    "author": "MedusaSorcerer",
    "description": "MedusaSorcerer的博客文档",
    "language": "zh-hans",
    "gitbook": "3.0.0",
    "structure": {
        "readme": "README.md"
    },
    "plugins": [
        "-highlight",
        "-github",
        "-search",
        "-lunr",
        "livereload",
        "back-to-top-button",
        "code",
        "prism",
        "copy-code-button",
        "search-pro",
        "splitter",
        "-sharing-plus",
        "tbfed-pagefooter",
        "click-reveal"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "modify_label": "该文件修订时间：",
            "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    },
    "links": {
        "sidebar": {
            "博客主页": "https://juejin.im/user/5da32395e51d4578200cc9c5/posts"
        },
        "sharing": {
            "google": false,
            "facebook": false,
            "twitter": false,
            "weibo": false,
            "all": false
        }
    }
}
复制代码

关键字	描述	示例
title	项目标题	MedusaSorcerer的博客文档
author	项目做者	MedusaSorcerer
description	项目描述信息	-
language	项目语言	查看下表
gitbook	Gitbook版本信息	3.0.0
structure	结构信息	{"readme": "README.md"} 指定readme的文件
plugins	须要安装或者禁用的插件名称	-
pluginsConfig	安装的插件须要自定义的配置	-
links.sidebar	文档添加其余连接地址	{"博客主页": "juejin.im/user/5da323…"} {名称:地址}
links.sharing	对文档的图标连接是否启用的配置	-

支持的语言列表, 版本之间存在差别, 仅供参考npm

语言简写	描述	语言简写	描述
en	英语	ar	阿拉伯语
bn	马来语	cs	捷克语
de	德语	es	西班牙语
fa	波斯语	fi	芬兰语
fr	法语	he	希伯来语
it	意大利语	ja	日语
ko	韩语	no	挪威语
pl	波兰语	pt	葡萄牙语
ro	罗马尼亚语	ru	俄语
sv	瑞典语	uk	乌克兰语
vi	越南语	-	-
zh-hans	简体汉语	zh-tw	繁体汉语

Gitbook插件介绍

安装的插件使用 "插件名" 注册在 plugins 里面便可, 禁用的插件使用 "-插件名"注册在 plugins 里面便可
默认启用的插件 highlight search sharing font-settings livereloadjson

插件名称	描述	举个栗子
highlight	代码高亮	-
search	导航栏英文检索功能	-
font-settings	字体设置	-
livereload	为GitBook实时从新加载	-
disqus	添加disqus评论	"plugins": [ "disqus" ], "pluginsConfig": { "disqus": { "shortName": "gitbookuse" } }
search-pro	支持中文搜索, 须要将默认的search插件去掉	"plugins": [ "-search", "search-pro" ], "pluginsConfig": { "search-pro": { "cutWordLib": "nodejieba", "defineWord" : ["Gitbook Use"] } }
advanced-emoji	支持emoji表情	"plugins": [ "advanced-emoji" ]
github	添加github图标	"plugins": [ "github" ], "pluginsConfig": { "github": { "url": "juejin.im/user/5da323…" } }
ace	使gitbook支持ace	"plugins": [ "ace" ]
emphasize	为文字加上底色	"plugins": [ "emphasize" ]
katex	支持数学公式	"plugins": [ "katex" ]
include-codeblock	使用代码块的格式显示所包含文件的内容	"plugins": [ "include-codeblock" ]
mermaid	支持渲染Mermaid图表	"plugins": [ "mermaid" ]
splitter	使侧边栏宽度可自由调节	"plugins": [ "splitter" ]
sharing	分享当前页面, 默认插件	"plugins": [ "-sharing" ] "pluginsConfig": { "sharing": { "weibo": true, "facebook": true, "twitter": true, "google": false, "instapaper": false, "vk": false, "all": [ "facebook", "google", "twitter", "weibo", "instapaper" ] } }
tbfed-pagefooter	为页面添加页脚	"plugins": [ "tbfed-pagefooter" ], "pluginsConfig": { "tbfed-pagefooter": { "copyright":"Copyright &copy zhangjikai.com 2015", "modify_label": "该文件修订时间：", "modify_format": "YYYY-MM-DD HH:mm:ss" } }
toggle-chapters	使左侧的章节目录能够折叠	"plugins": [ "toggle-chapters" ]
sectionx	将页面分块显示	"plugins": [ "sectionx" ]
codeblock-filename	为代码块添加文件名称	"plugins": [ "codeblock-filename" ]
ga	google 统计	"plugins": [ "ga" ], "pluginsConfig": { "ga": { "token": "UA-XXXX-Y" } }
baidu	百度统计	"plugin": [ "baidu" ], "pluginsConfig": { "baidu": { "token": "YOUR TOKEN" } }

Gitbook错误处理

执行 npm install gitbook-cli -g 的时候下载失败bash

进入你的 Users\当前用户\AppData\Roaming\npm\node_modules 目录下
查看是否有 gitbook-cli 目录

若是目录存在, 删除 gitbook-cli 目录
若是目录不存在, 使用 npm 卸载 Gitbook 遗留文件
再从新执行下载便可成功
复制代码

修改项目文件保存后, gitbook serve 不支持热加载
当你修改 Gitbook 项目保存后, serve 重启的时提示没法使用 mkdir 操做, 以致于不能达到重启的目的
那么你须要进行如下操做:markdown
- 找到你下载的gitbook版本文件夹: 通常位于Users\当前用户\.gitbook\versions\下会有对应版本号的文件夹名称
- 在对应版本文件夹内找到lib\cli\serve.js文件
- 复制如下代码放置serve.js文件中
```
/* 代码首行 */
const fs=require("fs");

/* 任意空白位置 */
function deleteFolder(path) {
let files = [];
if( fs.existsSync(path) ) {
    files = fs.readdirSync(path);
    files.forEach(function(file,index){
        let curPath = path + "/" + file;
        if(fs.statSync(curPath).isDirectory()) {
            deleteFolder(curPath);
        } else {
            fs.unlinkSync(curPath);
        }
    });
    fs.rmdirSync(path);
    }
}
复制代码
```
- 在serve.js找到函数体generateBook
- 在函数内var outputFolder = getOutputFolder(args);后另起一行写入如下代码
```
if (server.isRunning()) deleteFolder(outputFolder)
复制代码
```
- 保存退出, 重启gitbook, 发现热加载生效了
注意: 当你中止服务的时候, 若服务没有自动删除 _book 文件夹时, 你须要手动删除 _book 文件夹 ``ide

安装 Gitbook 后没有找到 gitbook 指令函数

须要在你的环境变脸中添加 Gitbook 的变量 Path
Users\当前用户\AppData\Roaming\npm
复制代码