第8章 自由地写作——GitBook

  在如今这样开放的互联网时代，每个人都可以是一个独立的品牌，可以表达自己的观点，也可以写一本自己的书。豆瓣阅读、百度阅读、网易云阅读、简书、知乎等平台都提供了很好的创作环境，可是它们也都有一定的门槛，那如何才能自由地、无门槛地进行写作呢?GitBook为我们提供了这种可能。

  小提示： 本书所提及的GitBook在没有特殊说明的情况下，均是指GitBook 命令行工具。由于www.gitbook.com在国内访问体验较差，因此不多作介绍。

8.1 你好，GitBook

  GitBook命令行工具是基于Node.js开发的，通过命令行可以创建、编辑和管理电子书。GitBook是目前最流行的开源书籍写作工具，其在写作方面主要有以下几点优势。

1. 支持Markdown和AsciiDoc语法。
2. 支持多语言，支持变量、模板和模板继承。
3. 可以导出静态站点或电子书（支持PDF、ePub、mobi等格式）。
4. 有丰富的插件。
5. 可以使用Git管理写作内容，方便多人协作和版本管理。
6. 可以将内容托管在GitHub或Gitlab中。

  使用GitBook可以搭建公司内部文档，用于内部的资料共享；也可以发布开源电子书，用于在互联网上分享知识。

8.1.1 环境配置

  安装GitBook前需要先安装Node.js，然后再通过命令来安装GitBook。

npm install gitbook-cli -g

8.1.2 快速开始

1. 创建静态站点

  先通过一个例子来快速了解GitBook的工作流程。

第1步，初始化工作目录

  根据上述代码，初始化完成后会创建两个md格式的文件。

1. README . md：用于编写书籍的前言或介绍。
2. SUMMARY . md：用于配置书籍的目录结构。

第2步：定义目录结构

  在SUMMARY.md文件中定义书籍的目录结构，主要有两种方法。

方法➊：先定义好目录结构，再通过gitbook init命令自动生成目录结构对应的文件夹和Markdown文件。
方法➋：先创建好文件夹和Markdown文件再来编辑目录结构。

  这里我们使用方法➊，在SUMMARY . md中定义书籍的目录结构

# SUMMARY

* [项目简介](README.md)
* [快速开始](docs/快速开始.md)
* [环境搭建](docs/环境搭建.md)
* [简单使用](docs/简单使用.md)
* [深入学习](docs/深入学习.md)

• 在项目根目录下执行

gitbook init

  所有不存在的文件夹和文件都会被新建出来。注意： gitbook init只支持生成两级目录。

第3步：启动服务

gitbook serve

  执行gitbook serve命令后，会先执行gitbook build编译书籍，如果编译没有问题，就会打开一个Web服务器，默认监听4000端口。如果编译有问题，则会抛出错误信息。

第4步：查看效果

  用浏览器打开http://localhost:4000/查看书籍站点的显示效果。

2. 开始写作

  推荐的写作工具组合是：GitBook（书籍管理）+Typora（编辑器）+SourceTree（版本控制），对于编写和管理电子书来说，这是一种非常高效的组合。当然，使用VS Code也是一个不错的选择。
  前面的的第3章和第4章已经介绍过Typora和VS Code。而SourceTree是一款Git可视化管理工具，如果你熟悉Git，那么SourceTree是很容易快速上手的，关于SourceTree的更多内容可以参考https://www.sourcetreeapp.com/。

3. 发布电子书

  GitBook不仅可以生成静态网站，也可以生成3种格式（即ePub、mobi、PDF）的电子书。

• 生成PDF格式的电子书

gitbook pdf ./mygitbook.pdf

4. 发布上线

  如果想要开源，可以把书籍托管到GitHub上，然后绑定自己的域名。一个比较好的例子是https://github.com/rootsongjc/kubernetes-handbook。

8.2 配置GitBook

8.2.1 GitBook的项目结构

• GitBook的项目结构

.
|—— book.json       # 配置书籍（可选）
|—— README.md       # 书籍的前言/介绍（可选）
|—— SUMMARY.md      # 配置的书籍目录（可选）
|—— GLOSSARY.md     # 配置书籍的词汇/注释术语列表（列表）
|—— .gitignore      # 配置要忽略的文件
|—— cover_small.jpg # 封面图片（小）
|—— cover.jpg       # 封面图片
|—— 第一章/         # 书籍内容
|   |—— README.md
|   |——something.md

1. 配置项目结构

  book.json是全局配置文件，可以自定义项目的根目录、自述文件、摘要、词汇表、多语言等文件的文件名。

• 在book.json中可配置的变量

• 配置 book.json 的一个示例

{
    "title": "Gitbook使用指南",
    "description": "Gitbook入门指南",
    "author": "XXX"
    "output.name": "site",              // 构建输出的文件名，使用默认即可，此项可删除
    "language": "zh-hans",              // 英文：en；中文简体：zh-hans；中文繁体：zh
    "gitbook": "3.2.2",
    "root": "."                         // 根目录为当前目录，使用默认即可，此项可删除
}

a. 自定义根目录和文件名

  在GitBook项目中，默认所有文件都是从根目录开始查找的，如果想自定义根目录，需要在book.json中通过root指定根目录。例如，将docs指定为项目的根目录。

{
    ......
    "root": "./docs"
}

  除root变量之外，还可以自定义GitBook的自述文件、摘要、词汇表和语言文件的名称，这些文件必须在书籍的根目录（或每种语言图书的根目录）下。

• 也可以自定义文件名和摘要

{
    ......
    "structure": {
        "readme": "myIntroduction.md",
        "summary": "mySummary.md"
    }
}

小提示： 为了避免出现更多错误，建议使用默认配置。

b. 配置链接

  如果搭建的是内部文档，要关闭分享链接。

{
    ......
    "links": {
        "sharing": {
            "google": false,
            "facebook": false,
            "twitter": false,
            "weibo": false,
            "all": false
        }
    }
}

  如果要在导航栏配置一些链接

{
    ......
    "links": {
        "sidebar": {
            "我的微博": "https://www.weibo.com/XXX",
            "我的博客": "https://www.blog.com/XXX"
            
        }
    }
}

c. 配置插件

• 在book.json中配置插件

• 配置插件的示例代码

{
    "plugins": [
        "插件名", "其他插件名"
    ],
    "pluginsConfig": {
        "插件名": {
            "插件属性1": true,
            "插件属性2": "test"
        }
    }
}

d. 自定义PDF文档的输出格式

• 在book.json中定制输出PDF格式的文档

• 定制PDF文档输出格式的示例代码

{
    "pdf": {
        "pageNumbers": false,
        "fontSize": 12,
        "paperSize": "a4",
        "margin": {
            "right": 62,
            "left": 62,
            "top": 36,
            "bottom": 36
        }
    }
}

e. 配置全局变量

  GitBook的变量分为预定义变量和自定义变量，变量在GitBook构建时会被替换。自定义变量又分为全局变量和局部变量，全局变量在book.json中定义，局部变量在文件中定义。

book.json中自定义全局变量的格式

{
    "variables": {
        "myName": "XXX",
        "myWeibo": "https://www.weibo.com/XXX"
    }
}

  可以像下面这样引用全局变量。

大家好，我是{{book.myName}}，我的微博是{{book["myWeibo"]}}

注意： 这里用了两种引用方式，类似Jinja2（一种模板语言）中的字典引用。

f. 一个比较通用的book.json

  为了省事，基础配置可以全部使用默认的，然后再定义一些常用的插件就可以了。

2. 配置目录

a. 基本用法

  在 SUMMARY . md 文件中定义书籍的目录结构，格式为链接列表，链接的标题将被作为章节的标题，链接所指向的目标是该章节所对应的文件的路径；如果向父章节添加嵌套列表，则会创建子章节。

注意： 每个章节都有一个 README . md，用来对子章节进行描述。

  然后使用gitbook init命令来创建目录中定义的这些文件。再使用gitbook serve命令启动服务。

b. 链接到标题

  当用鼠标单击目录时，可以打开页面并定位到指定的标题上，这个功能可以通过锚点来实现。

c. 分隔章节

  章节可以使用标题或水平线进行分隔。

注意： 用于分隔章节的“标题”没有 README . md ，在渲染后会显示成灰色，不可进行单击操作。

d. 显示目录层级序号

  如果想要显示目录中章节的层级序号，需要在book.json中开启showLevel

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

3. 配置多语言

  GitBook支持用多种语言编写书籍，如果配置了多语言，在打开站点的首页后会看到一个选择语言的页面。配置多语言在LANGS.md中进行。

• 格式示例

# Language

* [英语](en/)
* [法语](fr/)
* [中文](zh/)

注意： LANGS.md要被存放在项目的根目录下。

  目录结构按语言分类，每种语言都有一个独立的子目录，在目录中遵循单语言的配置规则。
  在根目录中有一个book.json文件作为主配置，在每种语言的子目录中也可以有一个book.json来定义自己的配置，它们将作为主配置的扩展存在。

注意： 插件比较特殊，它是全局指定的，无法配置属于某种语言的插件。

  GitBook官方提供了一个完整的例子https://github.com/GitbookIO/git

4. 配置词汇表

  在GLOSSARY.md中可以指定词汇及词汇的定义，GitBook会自动构建索引并在文中突出显示这些词汇。

## GitBook
这是一个使用Node.js开发的命令行工具

## GitBookEditor
GitBook自己的编辑器

注意： 词汇不能是中文。

  配置后，在其他页面使用这两个词汇时，它们会被突出显示，如果把鼠标放到上面，则会显示词汇的定义。

5. 配置要忽略的文件

  GitBook是通过Git进行管理的，一般IDE自动产生的文件和编译时产生的文件都是没有必要纳入到版本控制的，因此需要忽略这些文件。
  GitBook会通过读取.gitignore（推荐）、.bookignore和.ignore中的配置来获取要忽略的文件。

# 以#开头表示这是一个注释， 如果想匹配#， 则需要在前面加一一个转义符号\#

# 忽略文件test. md
test . md

# 忽略"bin"目录下的所有文件
bin/*

# 忽略所有node_ modules文件
node_ modules

# 忽略所有HTML格式的文件
*.html

# test.html例外，它不被忽略
! test.html

  如果不知道怎么配置.gitignore，可以参考https://github.com/github/gitignore。

8.2.2 不可不知的GitBook插件

  GitBook可以通过插件实现自身功能的扩展，一些插件可以让写作和查看书籍变得更加便捷。

1.插件的安装步骤

1. 找到插件

  由于GitBook将重心放在了网站上，原来的插件页面已不存在，我们只能通过搜索引擎或一些推荐找到想要的插件。

2. 配置插件

  在book.json中通过plugins和pluginsConfig字段配置插件名和插件属性。

{
    "plugins": ["myPlugin","anotherPlugins"]
}

  如果想指定特定的插件版本，则可以将插件名配置为“myPlugin@2.1.1”的样子；如果不指定版本，GitBook默认会使用最新的。是否需要配置插件属性（pluginsConfig），以及及如何配置，需要参考对应插件的官方文档。

3. 安装插件

  在项目根目录执行gitbook install来安装插件，仅供当前项目使用。

4. 禁用自带插件

• GitBook默认自带5个插件

1. highlight：代码高亮。
2. search：搜索。
3. sharing：分享。
4. font-settings：字体设置。
5. livereload：实时加载。

  这些自带的插件都非常有用，但或许你并不想用它们，

{
    "plugins": [
        "-search"   // 在自带的插件名前面加上一个 -
    ]
}

2. 自动生成目录

a. 自动生成文章的目录

  gitbook-plugin-atoc是一款自动生成文章导航目录的插件，使用它可以在文章的右上角自动生成悬浮的导航目录，可以快速定位到某一章节，比锚点（书签）用起来方便多了。

  ➊ 打开 gitbook-plugin-atoc 首页 https://plugins.gitbook.com/plugin/atoc，首页上提示有book.json的配置信息。

{
    "plugins": ["atoc"],
    "pluginsConfig": {
        atoc": {
            "addClass": true,
            "className": "atoc"
        }
    }
}

  ➋ 把如下代码添加到book.json中。

{
    "variables": {
        "myName": "XXX",
        "myWeibo": "www. weibo.com/XXX"
    },
    "plugins": ["atoc"],
    "pluginsConfig": {
        "atoc": {
            "addClass": true, 
            "className" : "atoc"
        }
    }
}

  检查json格式，地址为http://tool.oschina.net/codeformat/json，以确保没有语法错误。

  ➌ 安装插件

gitbook install

  当安装完成后，在文章的顶部插入下面的字符。

<!-- toc -->

  ➍ 启动server，查看渲染效果。

b. 自动为每个页面生成目录树

  很多页面的目录插件都需要我们手动插入，如ATOC就需要手动在每一个页面添加``，这确实比较麻烦。
  使用page-treeview可以解决这个问题，它会为每一个页面自动生成目录树。唯一的缺点是插件作者的版权声明会很突兀地显示在目录树下面，不过不影响使用。

➊ GitHub地址为https://github.com/aleen42/gitbook-treeview。

➋ 配置方式如下。

{
    "plugins": ["page-treeview"],
    "pluginsConfig": {
        "page- treeview": {
            "copyright": "Copyright © XXX",
            "minHeaderCount": "2",
            "minHeaderDeep": "2"
        }
    }
}

c. 自动为文章生成极简的导航模式

  anchor-navigation-ex插件可以为每篇文章自动生成目录，并支持两种导航模式，即浮动导航模式和页面内顶部导航模式。

➊ GitHub地址为https://github.com/zq99299/gitbook-plugin-anchor-navigation-ex。

➋ 配置方式如下。

{
    "plugins": ["anchor-navigation-ex"],
}

注意： 这里使用的是插件的默认配置，如需更改请参考官方文档。

3. 定制每篇文章的页脚

  tbfed-pagefooter插件可以用来定制每篇文章的页脚，可以添加版权信息和显示文件修改时间。

➊ GitHub地址为https://github.com/zhj3618/gitbook-plugin-tbfed-pagefooter。

➋ 配置方式如下。

{
    "plugins": [
        "tbfed-pagefooter"
    ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
            "copyright": "Copyright ◎xxx 2021",
            "modify_label": "该文件修订于:",
            "modify_format": "YYYY-MM-DD HH :mm: ss"
        }
    }
}

4. 搜索功能

  GitBook自带的search插件不支持中文搜索，使用起来非常不方便，还好search-pro插件横空出世，让搜索功能焕发出新的生机。

➊ GitHub地址为https：//github.com/gitbook-plugins/gitbook-plugin-search-pro。

➋ 配置方式如下。

{
    "plugins": [
        "-search","search-pro"   // 先禁用search
    ],
}

5. 自动生成并显示图片标题

  在写书时，通常会对文章中的图片添加一个描述信息，这里我们称之为图片的标题。

  在GitBook中可以使用image-captions插件自动生成并显示图片标题。这个插件会自动提取图片中alt或title的属性内容，作为标题显示在图片下面。

➊ GitHub地址为https://github.com/todvora/gitbook-plugin-image-captions。

➋ 配置方式如下。

{
    "plugins": [
        "image-captions"
    ],
    "pluginsConfig": {
        "image-captions": {
            "caption": "图 1.1 - _CAPTION_"
        }
    }
}

说明： CAPTION会被替换为图片title或alt中的文字。

➌ 标题文字中的可用变量如下所示。

1. PAGE_LEVEL：章节的编号。
2. PAGE_IMAGE_NUMBER：本章中图像的序列号。章节中的第1个图像取值为1。
3. BOOK_IMAGE_NUMBER：整本书中图片的序列号。书中的第1个图像取值为1。

• 以章节和章节中图像的序列号作为图片的标题

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

• 标题默认是居中对齐的，如果想左对齐，可以像下面这样设置

"image-captions": {
    "align": "left"     //右对齐为 right
}

6. 显示GitHub的Star和Fork数量

  github-button插件可以显示GitHub的Star和Fork的数量。

➊ GitHub地址https://github.com/azu/gitbook-plugin-github-buttons。

➋ 配置方式如下。

{
    "plugins": [
        "github-buttons"
    ],
    "pluginsConfig": {
        "github-buttons": {
            "repo": "Github用户名/项目名",
            "types": [
                "star",
                "watch"
            ],
            "size": "large "
        }
    }
}

说明： size是图标的大小，可选值为large或small。large为150x30，small为100x20。

• 支持做如下自定义
  1. "width":number.
  2. "height":number.

7. 自由调节侧边栏宽度

  默认侧边栏宽度是不能够调节的，如果想通过拖拽的方式自由调节侧边栏宽度，可以使用插件splitter。

➊ GitHub地址为https：//github.com/yoshidax/gitbook-plugin-splitter。

➋ 配置方式如下。

{
    "plugins": [
        "splitter"
    ],
}

8.显示捐赠打赏

  donate插件支持定义和显示支付宝和微信打赏。

➊ GitHub地址为https://github.com/willin/gitbook-plugin-donate。

➋ 配置方式如下。

{
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
            "wechat": "例: /images/1.png",
            "alipay": "http://blog.XXX.XXX/static/images/1.png",
            "title": "默认空",
            "button": "默认值: Donate",
            "alipayText": "默认值: 支付宝捐赠",
            "wechatText": "默认值:微信捐赠"
        }
    }
}

8.3 构建GitBook

  在本地构建书籍的命令是gitbook build，这个命令提供了很多参数可供选择，格式为build [book目录][输出目录]。

• 对命令及参数的解读

  1. build [book] [output]：构建一本书。
  2. -log：指定要显示的最小日志级别（默认值为info；可选值有debug、info、warn、error、disabled）。
  3. -format：指定要构建的格式（默认值为website；可选值有website、json、ebook）。
  4. -[no-]timing：打印定时调试信息（默认值为false）。

• 构建书籍输出格式有3种

  1. website：网站（默认输出到_book目录）。
  2. ebook：电子书（PDF、ePub、mobi）。
  3. json：提取书籍的元数据（概要，介绍等）。

8.3.1 生成静态网站

• 在项目的根目录下执行命令

gitbook build

  默认会把生成的静态网站放到_book目录下，相当于执行了gitbook build./_book。如果想更改地址，可以使用gitbook build [项目路径][输出路径]。如果想启动服务，查看生成的某个网站，则需要在根目录下执行gitbook sever。使用这个命令会先执行gitbook build构建书籍，然后再启动服务。服务启动后，可以通过http://localhost:4000/来查看效果。网站默认的端口是4000，如果想重新指定端口，则可以使用gitbook sever --port 4444

  一般我们只是在本地使用gitbook serve进行预览和调试，如果想把网站开放给他人使用，还需要将网站部署到服务器上。在部署时，不管是内部服务器还是外部服务器，一般都要遵循以下步骤。

1. 在服务器上安装GitBook及GitBook插件。
2. 生成静态网站，默认目录为_book。
3. 把网站复制到指定目录下。
4. 配置Nginx。
5. 启动Nginx。

8.3.2 生成电子书

  GitBook不仅可以生成静态网站，也可以生成3种格式（即ePub、mobi、PDF）的电子书，不过要依赖ebook-convert这个工具。

1.安装ebook-convert

  想安装ebook-convert则必须安装calibre，calibre是一个强大、易用、开源、免费的电子书管理工具。其安装步骤如下。

➊ 打开https://calibre-ebook.com/download下载对应的操作系统版本。
➋ 如果是Windows系统，按照提示一步一步安装即可。如果是Linux系统，其安装命令sudo aptitude install calibre。

小提示： 在一些GNU/Linux发行版中安装Node.js，需要手动创建一个软链接sudo ln-s/usr/bin/nodejs/usr/bin/node。

  如果是macOS系统，则应首先将calibre.app移动到应用程序文件夹中，并创建一个指向ebook-convert工具的软件链接。

sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert/usr/bin

然后，配置环境变量

vim ~/.bash_profile

# 添加配置
export EBOOK_PATH=/Applications/calibre.app/Contents/MacOS
export PATH=$PATH:$EBOOK_PATH

  更新配置的命令：source ~/.bash_profile。最后，测试ebook-convert是否能正常使用ebook-convret --version

2.设置封面

• 对封面图片的要求

  无论是大图（cover.jpg）还是小图（cover_small.jpg），都要放在本书的根目录下可以自已制作一张图片，也可以使用autocover插件生成一个，制作图片的注意事项如下。

1. 图片没有边界。
2. 图片上的书名要清晰可见。
3. 即使是小图，也要能够看清所有重要的文本。

3. 生成电子书

• 生成PDF格式的电子书，需要在电子书的根目录下执行gitbook pdf ./ ./mygitbook.pdf
• 生成ePub格式的电子书，执行gitbook epub ./ ./mygitbook.epub
• 生成mobi格式的电子书，执行gitbook mobi ./ ./mygitbook.mobi

8.4 本章小结

  本文详细介绍了如何使用GitBook进行写作，使用GitBook可以搭建内部的协作文档，可以导出多种格式的电子书，也可以放到 GitHub上开源。总之，使用GitBook可以自由无门槛地进行写作。