Gitbook安装及用法

Gitbook安装及用法

---

喜欢用markdown写点东西，把自己的知识整理起来，慢慢地越写越多了，感觉都可以构成一本小小的书了，于是想把这些东西都整理整理，搞成一本书。便于自己搜索、查看，Gitbook 可以很好地满足我的需求。

---

1、环境要求

• NodeJS（推荐使用v4.0.0及以上版本），我安装的10.14.1，高版本的运行gitbook init 会报错“cb.apply is not a function”
• Windows，Linux，Unix 或 Mac OS X

2、安装

安装 GitBook 的最好办法是通过 NPM。在终端提示符下，只需运行以下命令即可安装 GitBook：

$ npm install gitbook-cli -g

gitbook-cli 是 GitBook 的一个命令行工具。它将自动安装所需版本的 GitBook 来构建一本书。

执行下面的命令，查看 GitBook 版本，以验证安装成功。

$ gitbook -V

查看其他版本

$ gitbook ls-remote #列举可以下载的版本

下载并安装其他版本的GitBook

$ gitbook fetch beta #beta版

npm简介（可跳过）

NPM 的全称是Node Package Manager ，是Node.js的包(或模块)管理器， www.npmjs.com上有海量的Node.js包，供免费下载使用。 当安装Node.js时，NPM程序会被同时安装。包/package包含了一个模块所需的所有文件。模块是可以导入到项目中使用的JavaScript库。 下载包很简单。在命令行里，执行npm insall 包命令。

脚本语言需要一个解析器才能运行，JavaScript是脚本语言，在不同的位置有不一样的解析器，如写入html的js语言，浏览器是它的解析器角色。而对于需要独立运行的JS，nodejs就是一个解析器。 Node.js官方安装包及源码下载地址：https://nodejs.org/en/

npm常用命令

• 查看npm版本

  $ npm -v
  

• 查看各个命令的简单用法

  $ npm -l 
  

• 安装 卸载

  $ npm install   <packageName> 
  $ npm install [<@scope>/]<name>@<tag>  #安装指定模块的指定标签 默认值为(@latest),如npm install [email protected]
  

  当你执行npm install, npm会根据你在package.json中对各种依赖的定义去安装这些依赖

  $ npm update <name> [-g] #升级当前项目或全局的指定模块
  如: npm update express 
      npm update express -g
  

  $ npm uninstall <name> [-g]  #卸载当前项目或全局模块 
  如: npm uninstall gulp --save-dev  
      npm i gulp -g
  

​ 卸载后，你可以到 /node_modules/ 目录下查看包是否还存在，或者使用以下命令查看：
npm ls 查看安装的模块

• 安装路径

  $ npm config ls  #查看npm默认安装路径
  
  $ npm config set prefix "your  path"  #设置安装路,如："D:\download\node\local resposity"
  

  更换成淘宝镜像cnpm，输入：

  npm config set registry https://registry.npm.taobao.org

  npm install -g cnpm --registry=https://registry.npm.taobao.org

  然后配置cnpm的环境变量，若cnpm所在路径为：“D:\local software manager\download\node\node local resposity\cnpm”,则环境变量的路径为：“D:\local software manager\download\node\node local resposity”

3、编辑器

可以用 VsCode、Typora 等自己喜欢的来编辑，我用的Typora。

4、创建一本书

创建书

$ gitbook init

运行后如果当前目录下没有readme.md和SUMMARY.md，则会自动创建这两个文件， README.md 就是说明文档，而 SUMMARY.md 其实就是书的章节目录 。

GitBook 使用 SUMMARY.md 文件来定义本书的章节和子章节的结构。 SUMMARY.md 文件用于生成本书的目录。SUMMARY.md 的格式是一个链接列表。链接的标题将作为章节的标题，链接的目标是该章节文件的路径。

向父章节添加嵌套列表将创建子章节。

示例

* [简介](README.md)
* [测试](测试/README.md)
    * [测试规范](测试/测试规范/README.md)
        * [测试日报模板](测试/测试规范/测试日报模板.md)
        * [测试质量报告模板](测试/测试规范/测试质量报告模板.md)
        * [bug规范](测试/测试规范/bug规范.md)
        * [用例规范](测试/测试规范/用例规范.md)
        * [测试环境部署](测试/测试规范/测试环境部署.md)
        * [测试流程](测试/测试规范/测试流程.md)
        * [测试笔记](测试/测试规范/测试笔记.md)
    * [知识分享](测试/知识分享/README.md)
        * [Fiddler](测试/知识分享/Fiddler.md)
        * [Jmeter](测试/知识分享/Jmeter.md)
        * [UI自动化](测试/知识分享/UI自动化.md)
        * [Markdown](测试/知识分享/Markdown.md)

SUMMARY.md内容如上，运行gitbook init后将自动创建这些文件及其目录：

4、预览书籍

$ gitbook serve

运行该命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件，我们可以使用下面命令来生成网页而不开启服务器。

构建书籍：gitbook build

默认：将生成的静态网站输出到 _book 目录

指定路径：gitbook build [书籍路径] [输出路径]

指定端口：gitbook serve --port 2333

生成pdf格式：gitbook pdf ./ ./mybook.pdf

生成epub格式：gitbook epub ./ ./mybook.epub

生成 mobi 格式：gitbook mobi ./ ./mybook.mobi

目录结构

GitBook 电子书结构通常如下：

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

GitBook 特殊文件的功能：

文件	描述
book.json	配置 (可选)
README.md	前言或简介 (必需)
SUMMARY.md	电子书目录 (可选)
GLOSSARY.md	词汇/注释术语列表 (可选)

主要讲下 SUMMARY.MD 和 book.json。

SUMMARY.MD

这个文件主要决定 GitBook 的章节目录，它通过 Markdown 中的列表语法来表示文件的父子关系 ，下面是个示例（右边是预览效果）：

Parts 只是章节组，没有专用页面，但根据主题，它将在导航中显示。

book.json

该文件主要用来存放配置信息 ，GitBook 允许您通过 book.json 灵活的配置自定义您的电子书。

常规设置

变量	描述
root	包含所有图书文件的根文件夹的路径，除了 book.json
structure	指定自述文件，摘要，词汇表等的路径，参考 Structure paragraph.
title	您的书名，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。
description	您的书籍的描述，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。
author	作者名。在GitBook.com上，这个字段是预填的。
isbn	国际标准书号 ISBN
language	本书的语言类型 —— ISO code 。默认值是 en
direction	文本阅读顺序。可以是 rtl （从右向左）或 ltr （从左向右），默认值依赖于 language 的值。
gitbook	应该使用的GitBook版本。使用 SemVer 规范，并接受类似于 “> = 3.0.0” 的条件。
links	在左侧导航栏添加链接信息
plugins	配置使用的插件
pluginsConfig	配置插件的属性

{
    "title": "知识沉淀",
    "author": "test",
    "description": "测试相关知识沉淀",
    "language": "zh-hans",
    "gitbook": "3.2.3",
    "styles": {
        "website": "./styles/website.css"
    },
    "structure": {
        "readme": "README.md"
    },
    "links": {
        "sidebar": {
            "我的博客": "https://blog.csdn.net/weixin_42258032?spm=1000.2115.3001.5343"
        }
    }
}

添加了book.json后左侧多了我的博客：

插件

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 来安装新的插件。

如果要指定插件的版本可以使用 [email protected]，因为一些插件可能不会随着 GitBook 版本的升级而升级。

pdf

可以使用 book.json 中的一组选项来定制PDF输出：

变量	描述
pdf.pageNumbers	将页码添加到每个页面的底部（默认为 true）
pdf.fontSize	基本字体大小（默认是 12）
pdf.fontFamily	基本字体样式（默认是 Arial）
pdf.paperSize	页面尺寸，选项有： 'a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'b0', 'b1', 'b2', 'b3', 'b4', 'b5', 'b6', 'legal', 'letter' （默认值是 a4）
pdf.margin.top	上边界（默认值是 56）
pdf.margin.bottom	下边界（默认值是 56）
pdf.margin.right	右边界（默认值是 62）
pdf.margin.left	左边界（默认值是 62）

封面

封面用于所有电子书格式。您可以自己提供一个，也可以使用 autocover plugin 生成一个，我是自己在线制作了一个，挺好玩的。

要提供封面，请将 cover.jpg 文件放在书本的根目录下添加一个 cover_small.jpg 将指定一个较小版本的封面。封面应为 JPEG 文件。

好的封面应该遵守以下准则：

• cover.jpg 的尺寸为 1800x2360 像素，cover_small.jpg 为 200x262
• 没有边界
• 清晰可见的书名
• 任何重要的文字应该在小版本中可见

5、生成电子书

GitBook 可以生成一个网站，但也可以通过 ebook-convert输出内容作为电子书（ePub，Mobi，PDF）。

安装ebook-convert，下载地址：https://calibre-ebook.com/download_windows，安装完后会自动将安装目录添加到系统path中，如果没有则手动添加下。

# Generate a PDF file
$ gitbook pdf ./ ./mybook.pdf  #第一个目录为源，第二个为生成的书的存放位置

# Generate an ePub file
$ gitbook epub ./ ./mybook.epub

# Generate a Mobi file
$ gitbook mobi ./ ./mybook.mobi

我用的是Typora编辑器，图片默认保存到了Typora安装目录下的typora-user-images，生成pdf的时候报错 Invalid URI：

根据报错信息可知是图片找不到，但这个路径下是有这张图片的，但生成的时候找不到，猜测需要放到当前书的目录下才行，将图片全部复制到当前目录下，然后修改图片的地址为相对路径，再次生成就成功了（有点麻烦，哎…）

生成的书看着还不错：

完结，撒花。