Asciidoctor提供了一个名为`Asciidoctor`的{url-api-gems}/asciidoctor/{release-version}[Ruby API^]，用于解析、分析和转换AsciiDoc内容。这个API是为在应用程序、脚本、与其他Ruby软件的集成（如Rails、GitHub和GitLab）中使用，以及被其他语言使用而设计，例如Java（通过AsciidoctorJ）和JavaScript（通过Asciidoctor.js）。

这个页面探讨了API的目的和使用方式，展示了如何开始使用它，介绍了它的主要入口点，并提供了链接，您可以在其中找到更多信息，开始将其付诸实践。

何时使用API

如果你需要做的仅仅是将AsciiDoc文件转换为可发布的格式，比如HTML，那么asciidoctor命令行界面应该能满足你的需求。这里有一个示例，展示了如何使用命令行界面将AsciiDoc文档转换为HTML：

$ asciidoctor -d book -n -a toc=left -a source-highlighter=highlight.js document.adoc

这是一个使用API将文档转换为HTML的相同示例：

require 'asciidoctor'

Asciidoctor.convert_file 'document.adoc', doctype: :book, safe: :unsafe,
  attributes: { 'toc' => 'left', 'sectnums' => '', 'source-highlighter' => 'highlight.js' }

这个API调用可以通过使用简写形式声明文档属性来缩写。

require 'asciidoctor'

Asciidoctor.convert_file 'document.adoc', doctype: :book, safe: :unsafe,
  attributes: 'toc=left sectnums source-highlighter=highlight.js'

与命令行接口（CLI）相比，应用程序编程接口（API）允许你将处理过程分解成更小的步骤。通过这样做，你可以捕获单个步骤的结果，分析解析后的文档，与扩展中的文档模型交互，或者总体上获得对处理过程的更多控制。

在使用API时，我们主要讨论两个步骤：

加载

在这一步中，AsciiDoc内容被解析成一个文档对象模型。这个模型代表了一个内存中的AsciiDoc内容层级，作为Ruby对象的树状结构。这些对象代表了AsciiDoc文档中的元素，直到块级别，以及任何元数据，比如文档和块属性。

转换

在这一步，之前准备好的文档对象模型会通过转换器转换成特定的输出格式。协同转换器工作，处理器将文档对象模型中的每个节点传递给转换器进行转换。然后将结果合并，根据传递给API的选项，要么返回要么写入文件。

您可以使用 API 来一起执行这两个步骤（类似于 CLI），通过使用 convert 和 convert_file，或者先单独使用 load 和 load_file，然后在文档对象上调用 #convert。API 可以加载并转换 AsciiDoc 文件（load_file 和 convert_file）或字符串（load 和 convert）。[API entrypoints] 部分将更详细地介绍这些方法。

API是与Asciidoctor进行交互的主要方式，用于应用程序或集成库中。通过使用API，你可以避免需要通过子进程来调用Asciidoctor。你会发现这比CLI提供的处理控制要多得多。API在脚本中也是一个有用的工具，你可能需要深入到文档模型中，超出了扩展所能达到的地方。它在扩展的开发中也起着至关重要的作用。

让我们学习如何通过引入Asciidoctor库来开始使用API。

从 require 开始

要开始使用Asciidoctor API，您首先需要安装gem。gem提供了CLI和API。事实上，CLI使用API来处理AsciiDoc转换。

当你通过CLI与Asciidoctor交互时，你会使用`asciidoctor`命令，而当你使用API与Asciidoctor交互时，你会通过`Asciidoctor`模块上的方法来进行交互。

为了在Ruby脚本或应用程序中使用`Asciidoctor`模块，你必须使用Ruby的`require`函数来引入`asciidoctor`宝石(即gem包)。

require 'asciidoctor'

这条语句使得Asciidoctor中所有的{url-api-gems}/asciidoctor/{release-version}[公共APIs^]可用于你的Ruby代码。例如，我们可以使用以下语句来检查Ruby所需的Asciidoctor的版本：

puts Asciidoctor::VERSION
# => {release-version}

如果`require`语句失败了，请检查确保你已经安装了宝石（并且在GEM_PATH上可用）。

API 入口端点

命令行界面（CLI）主要用于转换AsciiDoc。虽然API也可以做到这一点，但它能做的更多。API不只是转换AsciiDoc，它允许你将AsciiDoc加载到文档模型中。从那里，你既可以将文档模型转换为输出格式，也可以暂停来分析或修改其结构。

Asciidoctor API有四个主要的入口点。

Asciidoctor.load

将AsciiDoc源代码（直到块级别）解析为`Asciidoctor::Document`对象。

Asciidoctor.load_file

将AsciiDoc源文件的内容（直到块级别）解析为一个`Asciidoctor::Document`对象。

Asciidoctor.convert

解析并将AsciiDoc源码转换为由指定后端决定的输出格式。

Asciidoctor.convert_file

解析并将AsciiDoc源文件的内容转换为由指定后端决定的输出格式。

如果你正在处理一个文件，你通常会使用一个以 _file 结尾的方法。否则，你会使用它的互补方法，该方法接受字符串、字符串数组或IO对象。

默认情况下，转换方法的输出遵循输入。如果您转换一个字符串，方法将输出一个字符串。如果你转换一个文件，方法将输出到一个文件。然而，这些默认设置可以使用选项进行更改（例如，:to_file）。

当通过API调用Asciidoctor时，你可以访问控制处理的额外选项，这些选项在使用CLI时是不可用的。例如，你可以传入扩展，仅解析标题，启用源代码映射，或编目资产。

除了主要入口点之外，API还提供了一种机制来注册和开发扩展。要了解更多关于扩展的信息，请参阅extensions:index.html。

下一步操作