功能

Asciidoctor 使用 Ruby 编写，这意味着它必须在 Ruby 语言运行时（包括 JRuby）上运行。但这是它唯一的先决条件。Asciidoctor 被打包并分发为 RubyGems 上的一个名为 asciidoctor 的 gem。该 gem 可以使用 Ruby 的包管理工具 (gem 或 bundle) 安装在 Ruby 支持的任何操作系统上。Asciidoctor 本身没有任何依赖项。

但如果您不熟悉 Ruby，或者出于任何原因不想安装它，该怎么办？没问题！借助 AsciidoctorJ 和 Asciidoctor.js，您可以在 Java 虚拟机 (JVM) 或 JavaScript 运行时上运行完全相同的 Asciidoctor 版本。这意味着您根本不需要在您的机器上安装 Ruby 运行时。AsciidoctorJ 在内部使用 JRuby，而 Asciidoctor.js 依赖于用 JavaScript 编写的类 Ruby 运行时。

无论您使用 Ruby、Java 还是 JavaScript，Asciidoctor 都易于获取，您可以立即开始使用。只有在您使用附加的转换器和扩展时，才需要安装依赖项。

Asciidoctor 提供了一个开箱即用的精美的 HTML 体验，包括默认样式表和内置集成，如 Font Awesome（用于图标）、Highlight.js（用于源代码高亮）和 MathJax（用于 STEM 处理）。当您刚开始使用 AsciiDoc 进行写作时，Asciidoctor 的 HTML 输出应该足以满足您所有的发布需求。

下面的前后对比图可以帮助您了解预期效果。

如果您需要更高级的输出，或者您已经拥有现有的 DocBook 工具链，您可以选择 转换为 DocBook 并将结果输入到该管道中。一旦您对 AsciiDoc 和 Asciidoctor 更加熟悉，您就可以探索使用模板自定义内置转换器，或者使用附加转换器来生成其他输出格式，例如 PDF 和 EPUB 3。因此，您有很大的成长空间。

Asciidoctor 默认提供三种输出格式的转换器：HTML 5、DocBook 5 和 man page（手动页的缩写）。这些转换器旨在满足大多数用户对基本预览和发布的需求。

HTML 转换器提供的结果可以直接发布到 Web，无需任何调整。DocBook 转换器允许您利用现有的发布工具链，或将内容迁移到不同的编写格式（无需工具知道如何解析 AsciiDoc）。man page 转换器极大地降低了制作系统帮助文件的门槛。

但还不止于此。Asciidoctor 中的转换器接口是一个扩展点。这意味着它可以用于创建任何可想象的输出格式的转换器。并且 Asciidoctor 项目中已经有了一个附加转换器的生态系统。您可以找到用于创建PDF、EPUB 3、Reveal.js 幻灯片等的转换器。Asciidoctor 还提供高级 docinfo 支持，用于将版权页（例如内容脚本）注入输出文件的页眉和页脚。

单一的输入格式 AsciiDoc，为您带来了多种输出格式。

虽然 Asciidoctor 提供了用于生成可发布 HTML 的内置转换器，但Asciidoctor 生成的所有 HTML 都可以更改。有两种方法可以修改 Asciidoctor 生成的 HTML：自定义转换器或转换器模板。

如果您是经验丰富的程序员，您可能会倾向于自定义转换器。您可以扩展内置的 HTML 转换器，并覆盖处理文档树中任何节点的转换方法。

如果您的专业知识更偏向技术写作，您可能会发现转换器模板更易于上手。这些模板可以使用 Tilt 模板抽象库支持的任何模板语言编写，例如 ERB、Haml 或 Slim。这些模板通过替换文档中节点的处理来增强内置转换器。您为希望控制转换的每种节点类型引入一个模板。模板允许您围绕 HTML（或类 HTML）标记块应用逻辑。

请记住，如果 Asciidoctor 生成的 HTML 不符合您的要求，您可以对其进行更改。

如果您正在编写包含源代码片段或配置的技术文档，您可以使用语法高亮（也称为源代码高亮）来增强这些源代码块的显示。语法高亮是一种对结构化编程语言或配置语言中的关键字和语法元素进行着色（或以其他方式强调）的做法。这里有一个例子可以帮助您了解。

Asciidoctor 为几个流行的语法高亮器（包括 Rouge 和 Highlight.js）提供了适配器。除了安装库（如果需要）之外，您只需要在文档中设置一个文档属性，Asciidoctor 就会处理其余的事情。之后，您可以配置语法高亮器的行为，例如更改样式/主题、启用行号以及突出显示特定行。

Asciidoctor 提供了两种处理 AsciiDoc 内容的接口：命令行接口 (CLI) 和应用程序编程接口 (API)。

CLI 被设计为一个简单的工具，供不希望编写程序即可转换 AsciiDoc 的非程序员使用，或用于在 CI 等自动化环境中进行内容转换。许多处理选项可以通过 CLI 使用选项标志进行访问。当您刚开始使用 Asciidoctor 时，最有可能通过 CLI 与其进行交互。虽然 CLI 本身不需要任何编程，但它仍然可以加载扩展代码来增强处理。

API 是为希望进一步处理 AsciiDoc 的程序员设计的。与 CLI 一样，您可以使用 API 来转换文档。但这不仅仅是关于转换为输出格式。Asciidoctor 以离散的步骤解析和转换源文档。这使得转换成为可选的，并为程序提供了通过与文档对象模型交互来提取、添加或替换文档中的内容的机会。或者，您可能希望利用转换为嵌入式文档的能力，以便与其他应用程序集成，例如静态站点生成器。API 还提供了一个扩展 SPI，您可以使用它来增强处理器，例如引入新语法、在转换前修改解析后的文档，或在转换后调整输出。

CLI 和 API 都可以处理 AsciiDoc 文件和作为字符串传递的 AsciiDoc 源。

关于 Asciidoctor 的介绍，不可能不提到它的速度。Asciidoctor 的速度几乎达到了 Ruby 程序所能达到的极限。它可以在大约十分之一秒 (~ 1MB/s) 的时间内加载、解析和转换一个 100K 的 AsciiDoc 文档。这比原始的 AsciiDoc 实现 AsciiDoc.py 快 100 倍以上。

Asciidoctor 的速度对于开发人员的生产力以及需要转换 AsciiDoc 标记的服务器端应用程序来说是个好消息。这也意味着像浏览器扩展这样的预览工具可以近乎实时地在 HTML 中呈现 AsciiDoc 内容的预览。

Asciidoctor 还可以通过提供几种安全（也称为 safe）模式来安全运行。使用这些安全模式之一，您无需担心在高度安全的环境中处理器访问敏感文件或文件系统。除了其性能之外，这些安全级别也使 Asciidoctor 非常适合服务器端部署。

安装 Asciidoctor 仅仅是您发布体验的开始。Asciidoctor 使您能够访问一个功能丰富的扩展和工具生态系统，包括附加转换器、扩展语法、构建插件以及集成的编写和预览环境。

一个流行的扩展是 Asciidoctor Diagram。加载后，Asciidoctor Diagram 允许您使用纯文本创建图表（就像 AsciiDoc 用于写作一样）。Asciidoctor Diagram 通过扩展 AsciiDoc 的语法来识别特殊标记的文字块来实现这一点。它获取这些块内的文本，将其传递给它集成的某个图表工具，并在处理文档时将其作为图像重新插入到文档中。结果是 AsciiDoc 文档中的图表源在生成的输出中成为一个图像。

另一个流行的工具是浏览器扩展。安装此扩展后，您可以浏览本地存储或 Web 上的 AsciiDoc 文件，浏览器将向您显示转换后的 HTML，而不是 AsciiDoc 源。这意味着您可以在不运行命令或脚本的情况下获得 Asciidoctor 提供的开箱即用的 HTML 体验。在浏览器中运行的扩展程序会为您处理所有事情。

这只是两个例子。在不断增长的 Asciidoctor 生态系统中，还有更多可能性等待您去探索。这个生态系统的所有组件协同工作，实现一个目标：让 AsciiDoc 写作成为一种有益且富有成效的体验。