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 的项目:
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
$ docker pull dawneve/gitbook:3.2.3
$ docker images
dawneve/gitbook 3.2.3 2bd76651845a 24 hours ago 1.18GB
容器内默认使用 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/
查询宿主机的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 *
# gitbook serve
Serving book on http://localhost:4000
这时,可以在宿主机上修改内容并查看效果。
等一切满意,就可以执行生成命令了。
# gitbook build
如果 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 上,作为静态网站,惊艳岁月。