Gitbook（honkit） 快速上手

1. 安装

首先需要安装 node.js：https://blog.lololowe.com/posts/a8e6/

image.png

由于 Gitbook 开源版早已经停止了更新，并转向了一个新的商业模型，因此这里选择安装 Gitbook 的另一开源分支 HonKit。

通过以下命令在全局安装：

1
sudo npm install -g honkit --save-dev

image-1.png

2. 实践

以阮一峰的 《中文技术文档的写作规范》 为例，演示克隆此教程的 Github 源码仓库，并将内部的 Markdown 文档通过 honkit 渲染成静态页面以及在线预览。

1
2
3
git clone git@github.com:ruanyf/document-style-guide.git
cd document-style-guide
tree

image-2.png

Gitbook 的主要结构由 README.md（书籍主页介绍） 和 SUMMARY.md（书籍目录） 两个文件决定（这两文件的文件名不区分大小写）。

仓库默认已经包含了 README.md 文件，因此还需要创建 SUMMARY.md 文件并添加目录名称以及文件引用，内容如下：

1
2
3
4
5
6
7
8
9
# Summary

* [标题](docs/title.md)
* [文本](docs/text.md)
* [段落](docs/paragraph.md)
* [数值](docs/number.md)
* [标点符号](docs/marks.md)
* [文档体系](docs/structure.md)
* [参考链接](docs/reference.md)

如果需要层级关系可使用制表符(Tab)分隔。

创建完成后，使用 honkit serve 命令即可启动一个默认监听在 4000 端口 http 服务（可通过 --port 选项修改端口）：

image-3.png

同时还会将静态资源保存在当前子目录 _book 下面：

image-4.png

如果不需要运行 http 服务，只需要静态资源文件，可使用 honkit build 命令。

3. 其他

  1. 插件：https://honkit.netlify.app/plugins/
  2. 导出 epub、mobi、pdf：https://honkit.netlify.app/ebook