Load and Convert Files Using the API

This page explains how to load and convert AsciiDoc files using the API.

Load an AsciiDoc file

When you load AsciiDoc using the API, you’re telling Asciidoctor to parse the document (down to the block level) and return an Asciidoctor::Document object. This object contains the full block structure of the AsciiDoc document.

Loading a document currently does not parse the inline content. That processing is deferred until the parsed document is converted.

Let’s assume we’re working with the following AsciiDoc document:

Example 1. document.adoc
= Document Title

The main content.
asciidoc

To parse this source file into an Asciidoctor::Document object, use the following API call:

doc = Asciidoctor.load_file 'document.adoc', safe: :safe
ruby

Using the object assigned to the doc variable, you can get information about the document, such as the document title.

puts doc.doctitle
# => "Document Title"
ruby

You can also inspect all the document attributes:

pp doc.attributes
ruby

Going deeper, you can find blocks in the document, such as all the paragraph blocks, using the find_by method:

puts doc.find_by context: :paragraph
# => #<Asciidoctor::Block@1001 {context: :paragraph, content_model: :simple, style: nil, lines: 1}>
ruby

However, if you’re only interested in converting the AsciiDoc source when using the API, then it’s better to use the convert_file entrypoint.

Convert an AsciiDoc file

When you convert AsciiDoc using the API, you’re telling Asciidoctor to parse and convert the document to the output format determined by the specified backend. If you don’t specify a backend, like with the CLI, Asciidoctor will produce HTML.

Let’s again assume we’re working with the following AsciiDoc document:

Example 2. document.adoc
= Document Title

The main content.
asciidoc

To convert this source file to HTML5, use the following API call:

Asciidoctor.convert_file 'document.adoc', safe: :safe
ruby

The command will output HTML to the file my-sample.html in the same directory. If you want Asciidoctor to output to a different file, you can specify it using the :to_file option:

Asciidoctor.convert_file 'document.adoc', safe: :safe, to_file: 'out.html'
ruby

You can convert the file to DocBook by setting the :backend option to 'docbook':

Asciidoctor.convert_file 'document.adoc', safe: :safe, backend: 'docbook'
ruby

In this case, Asciidoctor will output DocBook to the file my-sample.xml in the same directory. As before, you can use the :to_file option to control the output file.

Asciidoctor.convert_file 'document.adoc', safe: :safe, backend: 'docbook', to_file: 'out.html'
ruby

That covers the basics of loading and converting AsciiDoc using the API.