专栏目录

• Gitbook介绍
• Gitbook安装
• Gitbook简单使用
• Gitbook插件介绍
• Gitbook错误处理

专栏详情

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 输出为 PDF 文件
gitbook pdf . [PDF_Name]
复制代码

Gitbook简单使用

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

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

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

SUMMARY.md示例

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

项目根目录下可以创建 book.json 实现全局配置文件信息

{
    "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
        }
    }
}
复制代码

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

Gitbook插件介绍

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

Gitbook错误处理

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

   进入你的 Users\当前用户\AppData\Roaming\npm\node_modules 目录下
   查看是否有 gitbook-cli 目录
   
   如果目录存在, 删除 gitbook-cli 目录
   如果目录不存在, 使用 npm 卸载 Gitbook 遗留文件
   再重新执行下载即可成功
   复制代码

2. 修改项目文件保存后, gitbook serve 不支持热加载
   当你修改 Gitbook 项目保存后, serve 重启的时提示无法使用 mkdir 操作, 以至于不能达到重启的目的
   那么你需要进行以下操作:

   • 找到你下载的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 文件夹 ``

3. 安装 Gitbook 后没有找到 gitbook 指令

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

4. 使用 gitbook pdf . pdfname.pdf 执行生成 PEF 文件编码错误

   ① 在 https://calibre-ebook.com/ 下载安装包安装在本地
   
   ② 安装完成后右键安装桌面图标找到安装路径并复制
   
   ③ 右键我的电脑 -> 属性 -> 高级系统设置 -> 环境变量 -> 用户变量 -> 选中PATH -> 编辑
   
   ④ 将刚刚复制的文件路径粘贴在末尾空白行保存退出
   
   ⑤ 重新打开 CMD 或者其他交互窗口, 执行 gitbook 命令
   复制代码