什么是 Asciidoctor?

Asciidoctor 是一种 快速 的文本处理器和出版工具链,可以非常方便地将 AsciiDoc 转化成 HTML5、DocBook 5 或者 4.5、EPUB3、PDF 以及其他格式。 Asciidoctor 是 AsciiDoc 语法的一种主要实现。AsciiDoc 最早是由基于 Python 的 AsciiDoc 项目引入以及实现的。

Asciidoctor 是使用 Ruby 编写的,可以在任何 Ruby 运行时上使用,包括 JRuby。 它也可以通过 AsciidoctorJ 运行在 Java 虚拟机上,正式的 Java API 是由下面的 JRuby 来完成的,也可以有通过 Asciidoctor.js 在 JavaScript 中使用,Asciidoctor.js 是基于 Ruby 代码的转换编译出来的。

Asciidoctor 是使用 MIT 协议发布的开源项目。Asciidoctor gem 发布到了 rubygems.org,可以被安装到数个流行的 Linux 发行版上。该项目的 Git 库被托管在 Asciidoctor organization on GitHub,以求获得最大的参与。

当 Asciidoctor 旨在提供完全符合由 AsciiDoc Python 实现的 AsciiDoc 语法,它不仅仅是一个 AsciiDoc Python 版的克隆。

Asciidoctor 实现有什么独特之处?

Asciidoctor 将 AsciiDoc 源文件和字符串渲染成 HTML 5、DocBook 4.5 以及其他格式,包括 HTML 5 展示(deck.js, dzslides)。

下面高亮部分是最显著特效

内置的以及自定义的模板

Asciidoctor 使用一系列内置的 ERB 模板来生成 HTML 5 和 DocBook 4.5 格式的输出,结构上相当于 AsciiDoc 产生。 任何一个模板都可以使用自定义模板来替换,自定义模板可以使用 Ruby 生态环境中的模板语言。 自定义模板渲染由 Tilt 模板库(Ruby 生态系统中最流行的 gem 之一)来处理。

解析器和对象模

借助 Ruby 堆栈并不是 Asciidoctor 唯一的优势。 不同于 AsciiDoc 的 Python 实现,Asciidoctor 将源文档的解析和渲染放在了离散的步骤中。 这样使得渲染文档成为可选,并且 Ruby 程序通过与 Asciidoctor 组成的文档对象模型交互,进而有机会提取、添加或者删除文档中的信息。 开发人员可以利用 Ruby 编程语言的全部能力来处理文档内容。

性能和安全性

No coverage of Asciidoctor would be complete without mention of its speed. Despite not being an original goal of the project, Asciidoctor has proven startlingly fast. It loads, parses and renders documents 50 times as fast as the Python implementation. That’s good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup. Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments.

Ruby 之外

Asciidoctor 的应用不仅仅局限于 Ruby 社区。 感谢 JRuby,一个 Ruby 在 Java 虚拟机的移植版,Asciidoctor 也就可以应用在 Java 应用中。 有针对 Apache MavenGradle, 和 Rewrite 的插件可用。 这些插件是基于 Java integration library,专门用于 Asciidoctor 的。

Asciidoctor 还是顺带发布了命令行接口(cli)。 Asciidoctor 命令行接口,asciidoctor,是 AsciiDoc Python 发行版中 asciidoc.py 的一个顺带替代实现。

系统需求

Asciidoctor 作为一个 Ruby gem 发布,目前可以运行在 Linux、Mac 和 Windows 系统上 Ruby 1.8.7, Ruby 1.9.3, Ruby 2 (2.0.0 以及更新版), JRuby 1.7, JRuby 9000 and Rubinius 2 (2.0 以及更新版) 上。 我们也期望它将正常运行在其他版本的 Ruby 上。