使用 API 加载和转换字符串
本页介绍如何使用 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 方法将其转换为
doc.convert但是，如果您只对使用 API 时转换 AsciiDoc 源代码感兴趣，那么最好使用 convert 入口点。
转换 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，则包含目录 -
转换后的文档正文
-
页脚（除非设置了
nofootnotes属性）
作者和修订信息从不在嵌入式文档中显示。如果您需要显示这些信息，可以使用属性引用，例如 {author} 和 {revnumber}。
嵌入式文档旨在包含在模板中，例如静态站点生成器提供的模板。该模板负责提供内容正确呈现所需的样式和库集成。
独立输出
您仍然可以在转换字符串时生成独立文档。要将 AsciiDoc 字符串转换为独立输出文档，您需要显式将 :standalone 选项设置为 true。
puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true现在您将获得一个完整的 HTML 文件。独立输出提供了内容周围的框架，其中包括样式以及内容正确呈现所需的所有库集成（例如，默认样式表、MathJax 等）。如果您不将 :standalone 选项设置为 true，您将只获得嵌入式文档（即正文内容）。
当输入或输出是文件时，:standalone 选项默认启用。因此，要指示 Asciidoctor 从 AsciiDoc 字符串将独立 HTML 写入文件，:to_file 选项是强制性的。
Asciidoctor.convert '*This* is Asciidoctor.', to_file: 'out.html'如果您想在以文件开始时生成嵌入式输出，请将 :standalone 选项设置为 false。但是，大多数时候您会在转换文件时生成独立文档（这就是为什么它是默认设置）。
转换字符串时，默认情况下仅在使用 :standalone 选项时（如上所示，无论是隐式还是显式启用）才包含 TOC。但是，您可以通过将 toc 属性设置为 macro 并使用字符串本身的 toc::[] 宏来强制包含它，而不包含页眉和页脚。