1 引言

GitBook 是一个开源的文档编辑和托管平台,用于创建和维护文档、手册和电子书。它基于 Markdown 和 Git 技术,帮助用户方便地编写、编辑和发布文档。

GitBook 支持将文档输出为多种格式,包括网页、PDF、ePub 等,适用于不同的阅读和分享场景。

GitBook 还提供了团队协作的功能,可以方便多人共同编辑和维护文档。

可以将其部署在 gitbook 平台(https://legacy.gitbook.com/),由于需要科学上网,本文不做详细介绍,如果需要,请见最后的参考部分;也可以部署在本地或者自己的网站上

从功能角度,可以把 gitbook 看作网页版的 obsidian 或者 hexo。gitbook 工具实现前端,用户只需要关心文档的内容,遵循 gitbook 定义的规范,然后使用 gitbook 提供的命令行工具即可。

从逻辑角度看,它以主题为中心,可以把一个系列的文章梳理集中在同一主题之下,更有章法,适合用来写书或者手册。

利用 gitbook,很容易将一堆文档(比如团队 markdown 文档,培训文档)生成类似 wiki 的网页展示,风格简捷舒服;并且轻松地部署到本地和定时更新,如果需要还可以生成 pdf 格式的手册。

https://github.com/GitbookIO/gitbook Start 25.9K

2 原理

其底层基于 Markdown,git,以及一些前端和文档转换技术。

用法和 vue, react, hexo 这些前端工具差不多。

GitBook 的客户端工具是 GitBook CLI,它是一个命令行的工具,用于创建、构建和发布 GitBook 项目;使用 JavaScript 编写的,依赖于 Node.js 环境。

其主要功能包括:

  • 创建项目
  • 本地预览
  • 构建静态网站
  • 生成电子书
  • 发布到 GitBook 平台
  • 安装插件

3 方法

3.1 环境

下载可用的 node docker 环境

1
2
$ docker pull node:9
$ docker run --rm -it -name node_9 --network host -v /exports/:/opt/xieyan node:9 bash

注意:这个项目产生比较早,使用最近的工具链可能出现各种问题。l 建议使用低版本的 node,否则可能因为工具链版本不匹配报 graceful-fs 包相关的错误,我用 node 16 docker 后试降 graceful-fs 版本,但没有成功。

3.2 安装

1
2
$ npm install gitbook-cli -g
$ gitbook --version # 第一次使用时自动安装 gitbook

3.3 新建项目

1
2
3
4
$ mkdir book
$ cd book
$ gitbook init
$ tree -Na

3.4 启动服务

1
$ gitbook serve --port 4001

3.5 打包

1
$ gitbook build

3.6 生成电子书

1
2
3
$ gitbook pdf . 输出文件路径.pdf
$ gitbook epub . 输出文件路径.epub
$ gitbook mobi . 输出文件路径.mobi

注意:gitbook 借助 ebook-convert 实现格式转换,因此需要安装 calibre。

4 参考

  • gitbook 入门文档

    https://segmentfault.com/a/1190000017960359

  • gitbook 安装教程

    https://blog.csdn.net/raspi_fans/article/details/129570510