使用 API 加载和转换文件
本页介绍如何使用 API 加载和转换 AsciiDoc 文件。
加载 AsciiDoc 文件
当您使用 API 加载 AsciiDoc 时，您是在告诉 Asciidoctor 解析文档（直至块级别）并返回一个 Asciidoctor::Document 对象。此对象包含 AsciiDoc 文档的完整块结构。
| 加载文档目前不会解析内联内容。该处理会推迟到解析后的文档被转换时进行。 |
我们假设正在处理以下 AsciiDoc 文档
= Document Title
The main content.要将此源文件解析为 Asciidoctor::Document 对象，请使用以下 API 调用
doc = Asciidoctor.load_file 'document.adoc', safe: :safe使用分配给 doc 变量的对象，您可以获取有关文档的信息，例如文档标题。
puts doc.doctitle
# => "Document Title"您还可以检查所有文档属性
pp doc.attributes深入了解，您可以使用 find_by 方法在文档中查找块，例如所有段落块
puts doc.find_by context: :paragraph
# => #<Asciidoctor::Block@1001 {context: :paragraph, content_model: :simple, style: nil, lines: 1}>但是，如果您只希望在使用 API 时转换 AsciiDoc 源，那么最好使用 convert_file 入口点。
转换 AsciiDoc 文件
当您使用 API 转换 AsciiDoc 时，您是在告诉 Asciidoctor 解析文档并将其转换为由指定后端确定的输出格式。如果您不指定后端，就像使用 CLI 一样，Asciidoctor 将生成 HTML。
我们再次假设正在处理以下 AsciiDoc 文档
= Document Title
The main content.要将此源文件转换为 HTML5，请使用以下 API 调用
Asciidoctor.convert_file 'document.adoc', safe: :safe该命令将在同一目录下的 my-sample.html 文件中输出 HTML。如果您希望 Asciidoctor 输出到其他文件，您可以使用 :to_file 选项指定它
Asciidoctor.convert_file 'document.adoc', safe: :safe, to_file: 'out.html'通过将 :backend 选项设置为 'docbook'，您可以将文件转换为 DocBook
Asciidoctor.convert_file 'document.adoc', safe: :safe, backend: 'docbook'在这种情况下，Asciidoctor 将在同一目录下的 my-sample.xml 文件中输出 DocBook。和以前一样，您可以使用 :to_file 选项来控制输出文件。
Asciidoctor.convert_file 'document.adoc', safe: :safe, backend: 'docbook', to_file: 'out.html'以上介绍了使用 API 加载和转换 AsciiDoc 的基本知识。