分享 Asciibook - 基于 AsciiDoc 的电子书生成工具

Rei · 2020年02月11日 · 最后由 aa1122 回复于 2020年04月22日 · 4356 次阅读

Asciibook 是一个电子书生成工具,可以将 AsciiDoc 转换为 HTML/PDF/EPUB/MOBI 格式的电子书。

相信大家已经看过不少电子书了,国外的技术出版社已经走上纸书电子书同步出版的方式,甚至电子书预览版会抢先提供试读。不过目前并没有很完善的面向技术作者的开源电子书制作工具,我接触过一些技术作者都是自己写脚本,粘合各种电子书生成器,在写作以外花费了很多精力,效果也不尽如人意。几年前我产生过做一个电子书生成器的想法,但是 GitBook 的出现打消了我的想法。

GitBook 是先前的最优选择,它几乎在每个环节都做了正确选择,有很多开源书籍都通过 GitBook 生成。但是他们在 2018 年底放弃了这个项目,转型成了团队协作工具。对于这个转变我觉得非常可惜,目前环境并不缺一个团队协作工具,但是缺一个电子书生成器。与此同时我重拾了我的想法,想把心目中的工具做出来。

经过一个多月的开发,终于实现了一个初步可用的版本,现在把它发布出来,希望有需要的人可以试用并提供意见,一起完善这个工具。

项目地址 https://github.com/asciibook/asciibook ,官网还在建设中。它提供的特性有:

  • 支持 HTML/PDF/EPUB/MOBI 格式。
  • 基于命令行,通过 docker 分发,适合用于 CI/CD。
  • 基于 HTML/CSS/JavaScript 的主题系统(文档稍后提供)。
  • 支持 latexmath 。

为了展示效果,我用《Pro Git》中文版的源码生成了一份电子书,请看 https://asciibook.org/progit2-zh/

安装

Asciibook 使用 docker 分发,首先到这里下载安装 docker https://www.docker.com/products/docker-desktop

然后 pull Asciibook 的镜像:

$ docker pull asciibook/asciibook:0.0.2-cjk-sc

这个 tag 是预装了中文字体 Noto CJK 并设置为简体中文的镜像

使用

在工作目录进入容器环境:

$ docker run -it -v $(pwd):/asciibook asciibook/asciibook bash
/asciibook #

后面的命令在容器中执行。

生成多种格式的电子书:

/asciibook # ascibook build mybook.adoc

生成部分格式电子书:

/asciibook # asciibook build mybook.adoc --format html
/asciibook # asciibook build mybook.adoc --format pdf,mobi

如果不想重复输入参数,可以为文档生成一个配置文件:

/asciibook # asciibook init mybook.adoc

修改新生成的 asciibook.yml 配置文件的内容,然后下次构建的时候输入命令:

/asciibook # asciibook build

更详细的用法例如自定义样式、模版的文档还在写,敬请期待。

其它

为什么用 AsciiDoc?

AsciiDoc 设计初衷就是面向大型文档,提供了 Markdown 不支持的很多特性,例如目录,内部引用,表格,自定义块等等。内置提供这些功能就不需要通过扩展实现,也不会遇到不同工具对扩展语法不兼容的问题,所以用 AsciiDoc 作为源码格式会更稳定。

要快速了解 AsciiDoc 的语法可以看 https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

写书也要 CI/CD 吗?

写书的过程和写程序其实很类似,由一个人或者多个人修改源码,对某些内容讨论、标注、修改,期间不停构建,发布。所以用纯文本编写,用源码管理工具协作,用 CI/CD 构建发布是技术作者的优势。

延伸阅读:Living the Future of Technical Writing https://hackernoon.com/living-the-future-of-technical-writing-2f368bd0a272

這次也是類似上次 走 htmlbook 的路線嗎?

lulalala 回复

之前打算 htmlbook 做中间格式的,后来开发中发现 htmlbook 没什么用,不如直接 AsciiDoc 到目标 html。

所以 asciidoctor-htmlbook 这个 gem 放置处理了。

好赞,正好有场景可以试一下。

Rei 回复

好奇繼續問,這代表以前你提到過的幾項障礙已經漸漸不是問題囉?

lulalala 回复

是指 asciidoctor 的问题吗?Asciibook 只用它解析 asciidoc,converter 部分重新实现,解决了我认为它存在的问题。

需要 登录 后方可回复, 如果你还没有账号请点击这里 注册