这个页面解释了如何使用API加载和转换AsciiDoc字符串。一个字符串就是裸露的AsciiDoc内容（通常是文件的内容）。

加载一个AsciiDoc字符串

要将AsciiDoc字符串解析为文档对象模型，请使用：

doc = Asciidoctor.load '*This* is Asciidoctor.'

你也可以从文件中读取AsciiDoc并将其传递给`load`方法：

asciidoc = File.read 'document.adoc', mode: 'r:utf-8'
doc = Asciidoctor.load asciidoc, safe: :safe

一旦你加载了文档，你可以通过调用convert方法来转换它：

文档转换

然而，如果你只对使用API时转换AsciiDoc源码感兴趣，那么最好是使用一个转换入口点。

把一个AsciiDoc字符串转换

要将AsciiDoc字符串直接转换为HTML，请使用：

puts Asciidoctor.convert '*This* is Asciidoctor.'

以下是你将看到的输出：

<div class="paragraph">
<p><strong>This</strong> is Asciidoctor.</p>
</div>

您也可以从一个文件中读取AsciiDoc，并将其传递给`convert`方法：

asciidoc = File.read 'document.adoc', mode: 'r:utf-8'
html = Asciidoctor.convert asciidoc, safe: :safe

当转换字符串时，Asciidoctor默认情况下_不会_输出独立文档。相反，它生成嵌入式输出。让我们了解为什么会这样以及如何控制它。

嵌入式输出

当你将一个AsciiDoc字符串传递给`Asciidoctor.convert`来转换成一个后端格式，比如HTML，:standalone`选项默认是`false。这意味着这个方法只返回转换后的内容。这个内容不包括围绕这个内容的框架（即，头部和尾部）包含在一个独立文档中。换句话说，它制作了一个_嵌入式_文档。选择这个默认值是为了使Asciidoctor与其他轻量级标记处理器如Markdown保持一致。

嵌入文档中包含以下内容：

  • 如果设置了`showtitle`属性，文档的标题是什么

  • 如果设置了`toc`属性且其值不是`preamble`，则目录为Contents。

  • 转换后的文档正文

  • 除非设置了`nofootnotes`属性，否则脚注不会改变。

嵌入文档中永远不会显示作者和修订信息。如果您需要显示该信息，可以使用属性引用，例如 {author} 和 {revnumber}。

嵌入的文档旨在包含在模板中，例如由静态网站生成器提供的模板。 该模板负责提供内容正确渲染所需的样式和库集成。

独立输出

你仍然可以在转换字符串时生成一个独立的文档。要从AsciiDoc字符串转换为独立的输出文档，你需要显式地将 :standalone 选项设置为 true。

puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true

现在，您将获得一个完整的HTML文件。独立输出提供了围绕内容的框架，包括样式和内容需要正确渲染的所有库集成（例如，默认样式表，MathJax等）。如果您没有将`:standalone`选项设置为`true`，您只会得到嵌入式文档（即，仅包含body内容的部分）。

当输入或输出是一个文件时，默认启用`:standalone`选项。因此，要指示Asciidoctor从AsciiDoc字符串写入独立HTML到文件，`:to_file`选项是必须的。

Asciidoctor.convert '*This* is Asciidoctor.', to_file: 'out.html'

如果您想在从文件开始时生成嵌入式输出，请将`:standalone`选项设置为`false`。然而，大多数时候，在转换文件时您会想要生成一个独立的文档（这也是为什么它是默认设置）。

在转换字符串时，仅当使用上面显示的 :standalone 选项（无论是隐式还是显式启用）时，默认才会包含目录（TOC）。然而，您可以通过将 toc 属性设置为 macro 的值，并在字符串本身中使用 toc::[] 宏，强制它不包括页眉和页脚而被包含进来。

仅转换内联标记

如果你只想要返回内联标记，请将`:doctype`选项设置为’inline'`：

puts Asciidoctor.convert '*This* is Asciidoctor.', doctype: 'inline'

在这种模式下，Asciidoctor 只会处理文档中的第一个区块（例如，段落），并忽略其余部分。

转换为DocBook

你可以通过将 :backend 选项设置为 'docbook' 来生成 DocBook 5.0。由于嵌入式 DocBook 不是很有用，我们还通过将 :standalone 选项设置为 true 来启用独立文档（即，页眉和页脚）。

puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true, backend: 'docbook'