Asciidoctor 文档

这是名为 Asciidoctor 的 Ruby 版 AsciiDoc 处理器的文档。Asciidoctor 目前是解释 AsciiDoc 语言的参考实现。如果您正在寻找 AsciiDoc 语言的文档，请参阅本网站的 AsciiDoc 部分。

什么是 Asciidoctor？

Asciidoctor 是一个快速、开源的文本处理器，用于解析 AsciiDoc 到文档模型，然后将其转换为输出格式，如 HTML 5、DocBook 5、man(ual) 页、PDF 和 EPUB 3。Asciidoctor 是用 Ruby 编程语言编写的。

当我们在文档的这个区域使用“Asciidoctor”这个名字时，我们指的是核心 Asciidoctor Ruby 处理器，简称为Asciidoctor core或Asciidoctor Ruby。我们添加“core”这个限定词是因为 Asciidoctor 也是提供运行时、扩展和工具来处理 AsciiDoc 的项目套件的名称。

为了简化安装，Asciidoctor 被打包成一个名为 asciidoctor 的 gem，并发布到位于 RubyGems.org 的 gem 托管服务上。一个 gem 是一个打包的 Ruby 应用程序或库（在本例中两者都是）。**asciidoctor** gem 可以直接从 RubyGems.org 在所有主要操作系统上使用 Ruby 打包工具（gem 或 bundle）进行安装。Asciidoctor 也分发为 Docker 镜像、许多 Linux 发行版的包以及 macOS 的包（通过 Homebrew 和 MacPorts）。

Asciidoctor 是在 MIT 许可条款下可用的开源软件，并 托管在 GitHub 上。

Asciidoctor 是 AsciiDoc.py 的后继者，AsciiDoc.py 是用于 AsciiDoc 语言的旧版 Python 处理器。如果您正在使用 AsciiDoc.py，请按照 从 AsciiDoc.py 迁移 来了解如何升级到 Asciidoctor。

基本用法

Asciidoctor 提供了两个用于处理 AsciiDoc 文档的接口，一个是名为 asciidoctor 的 CLI，另一个是名为 Asciidoctor 的 Ruby API。下表为您展示了如何使用这些接口。

CLI API 
$ asciidoctor document.adoc
 
require 'asciidoctor'
Asciidoctor.convert_file \
  'document.adoc', safe: :safe

请参阅 通过 CLI 处理 AsciiDoc 以了解更多关于此接口的信息。

请参阅 通过 API 处理 AsciiDoc 以了解更多关于此接口的信息。

与 AsciiDoc 的关系

AsciiDoc 是语言。
Asciidoctor 是处理器。

您使用 AsciiDoc 语言撰写文档，这是一种基于文本的书写格式。AsciiDoc 语言的设计力求不显眼且简洁，以简化书写并使其更令人愉悦。但 AsciiDoc 本身并不是一种发布格式。它更像是一种速记。这就是 AsciiDoc 处理器发挥作用的地方。

Asciidoctor 等 AsciiDoc 处理器会读取 AsciiDoc 源文件，并将其转换为可发布的格式，如 HTML 5 或 PDF。它也可以将其转换为可以由发布工具链处理的格式，如 DocBook。

由于 AsciiDoc 不是直接发布的，因此处理步骤提供了一个机会来增强文档，方法是展开速记代码、添加集成并应用令人愉悦的视觉风格。这种增强是 Asciidoctor 所做工作的重要组成部分。

简而言之，您将 AsciiDoc 源提供给 Asciidoctor，它会为您提供可发布的结果。

生态系统

在此部分中，当我们谈论 Asciidoctor 时，我们指的是核心处理器和内置转换器。Asciidoctor 还有一个由扩展、转换器、构建插件和工具组成的生态系统，可以帮助您编写和发布用 AsciiDoc 编写的内容。您可以在本网站的其他地方或 GitHub 上的 Asciidoctor 组织中找到这些项目的文档。

超越 Ruby

尽管 Asciidoctor 是用 Ruby 编写的，但这并不意味着您需要 Ruby 才能使用它。您也可以通过 AsciidoctorJ 使用 JVM 运行 Asciidoctor，或通过 Asciidoctor.js 使用 JavaScript 运行。

Java / JVM

得益于 AsciidoctorJ，Asciidoctor 可以在任何在 Java 虚拟机 (JVM) 上运行的程序中使用。在底层，AsciidoctorJ 使用 JRuby 来运行 Asciidoctor，但这隐藏在 Java API 后面。AsciidoctorJ 甚至提供了一个替代的 CLI，这意味着您只需 Java 运行时即可获得完整的 Asciidoctor 体验。基于 AsciidoctorJ，还有一些插件可以将 Asciidoctor 集成到 Apache Maven、Gradle 或 Javadoc 构建中。

JavaScript

得益于 Asciidoctor.js，Asciidoctor 也可以在 JavaScript 中使用。Asciidoctor.js 项目使用 Opal 将 Asciidoctor 中的 Ruby 源代码转译为 JavaScript。结果是一个功能齐全的 Asciidoctor 版本，可以在任何 JavaScript 运行时（如现代浏览器或 Node.js）上运行。Asciidoctor.js 甚至提供了一个替代的 CLI，这意味着您只需 JavaScript 运行时即可获得完整的 Asciidoctor 体验。Asciidoctor.js 用于为 Chrome、Atom、Brackets 和其他基于 Web 的工具提供 AsciiDoc 语言预览扩展。

准确地说，您可以使用 Ruby、JVM 或 JavaScript 来运行 Asciidoctor。本文档重点介绍 Ruby 版的 Asciidoctor。