report | 使用 Docker版的 gitbook 把 markdown 转为 html 报告 (静态站点)

GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书，GitBook 并非关于 Git 的教程。

使用GitBook制作电子书，必备两个文件：README.md和SUMMARY.md

gitbook 的基本用法非常简单，基本上就只有两步：

• 使用 gitbook init 初始化书籍目录，可以根据你的目录文件 SUMMARY.md 生成文件目录。
• 使用 gitbook build 编译书籍为静态网页，默认输出到 _book/。
• 使用 gitbook serve 本地构建并运行服务,默认访问 http://localhost:4000 实时预览.

我们先看一下效果：

gitbook很适合生成网页报告。以上是暗色主题，默认是白色主题。

使用 gitbook 的项目:

• 算法笔记
• 阿里Java规范
• GitBook 帮助

gitbook cli 是一个能把 markdown 生成 html 静态站点的命令行工具，不过随着前几年官方开启 GitBook.com 的商业化进程，该cli工具事实上被放弃开发了，甚至其兄弟组件 GiBook editor 已经在github上找不到了。见利忘义的商家。。。

目前该cli工具已经4年没有更新了，在最新的node下报错。经过我的少量测试，最新稳定版的 gitbook 3.2.3 能在node 6.0.0 到 node 13.12.0 运行(v14.0.0下运行报错)，少量小版本也会报错，比如 node 12.22.3。

为了方便使用该工具，我把其环境抢救性的打包成了Docker镜像，方便大家使用。

# node --version
v13.12.0

1. 下载镜像

$ docker pull dawneve/gitbook:3.2.3
$ docker images
dawneve/gitbook              3.2.3      2bd76651845a   24 hours ago    1.18GB

2.启动容器

容器内默认使用 4000 端口。可选项–rm，停止就删除。
-p的第一个参数8896是宿主机的端口，根据自己的情况选择。

$ docker run -it -d --name gitbook2 --rm -p 8896:4000 -v /data/wangjl/test/GitBook:/home/tom/GitBook dawneve/gitbook:3.2.3 bash

$ docker exec -it gitbook2 bash
# cd /home/tom/GitBook/

3. 修改权限

查询宿主机的uid
$ id #check your uid on host
uid=1001(wangjl) gid=1001(wangjl) groups=1001(wangjl),1004(docker)

修改容器内用户的uid
Change the uid of user tom in containner to your id on the host, shown above.
# usermod -u 1001 tom

修改文件的权限
# chown -R tom *

4. 开始启动web服务

# gitbook serve
Serving book on http://localhost:4000

这时，可以在宿主机上修改内容并查看效果。
等一切满意，就可以执行生成命令了。
# gitbook build

5. 只使用构建功能

如果 markdown 文件是代码生成的，想转为html文件，还可以尝试一次性构建命令。

$ docker run --rm -v "$PWD:/home/tom/GitBook" -p 4000:4000 dawneve/gitbook:3.2.3 bash -c "cd /home/tom/GitBook && gitbook build && usermod -u `id -u $USER` tom && chown -R tom _book"

主要的过程:
* 开启容器，进入文件夹
* 构建
* 修改容器用户tom的uid为当前宿主机用户的uid
* 修改文件夹_book 的所有者为当前用户，忽视分组。

小结: gitbook cli 这个系统很适合制作 测序分析的报告，特别是 一步法docker构建命令，能整合到流程中。

最后的html文件也可以发布到 github pages 上，作为静态网站，惊艳岁月。