Process AsciiDoc Using the API

In addition to a CLI, Asciidoctor provides a Ruby API named Asciidoctor for parsing, analyzing, and converting AsciiDoc content. This API is intended for use in scripts, integration with other Ruby software, such as Rails, GitHub, and GitLab, and by other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).

This page covers how to get started with the Asciidoctor API, introduces its primary entry points, and explains where to get more information so you can use the API for more advanced use cases.

Use require to get started

To get started with the Asciidoctor API, you first need to install the gem. The gem provides both the CLI and the Ruby API. In fact, the CLI uses the API to handle AsciiDoc conversion.

Whereas with the CLI, you interact with Asciidoctor using the asciidoctor command, when using the API, you require the asciidoctor gem using Ruby’s require function. From there, you interact with the Asciidoctor API.

To start using the Asciidoctor API in your application or script, you first need to require the gem as show here:

require 'asciidoctor'

This one statement makes all of the public APIs in Asciidoctor available to your Ruby code. For example, we can check which version of Asciidoctor was required by Ruby using the following statement:

puts Asciidoctor::VERSION
# => 2.0.15

If the require statement fails, check to make sure that you have the gem installed (and available on the GEM_PATH).

API entrypoints

The CLI is focused on converting AsciiDoc to various output formats. While the API can do that as well, it can do so much more. Instead of just converting AsciiDoc, the API allows you to load the AsciiDoc into a document model. From there, you can either convert the document model to an output format, or you can pause to analyze or modify its structure.

There are four main entrypoints in the Asciidoctor API:

Asciidoctor.load

parses the AsciiDoc source (down to the block level) into an Asciidoctor::Document object

Asciidoctor.load_file

parses the contents of the AsciiDoc source file (down to the block level) into an Asciidoctor::Document object

Asciidoctor.convert

parses and converts the AsciiDoc source to the output format determined by the specified backend

Asciidoctor.convert_file

parses and converts the contents of the AsciiDoc source file to the output format determined by the specified backend

If you’re processing a file, you’d typically use a method that ends with _file. Otherwise, you’d use its complement, which accepts a String, an array of Strings, or an IO object.

By default, the output of the convert methods follows the input. If you convert a String, the method will output a String. If you convert a file, the method will output to a file. However, these defaults can be changed using the options (e.g., :to_file).

When calling Asciidoctor using the API, you can access additional options that control processing which are not available when using the CLI. For example, you can pass in extensions, parse only the header, enable the sourcemap, or catalog assets.

In addition to the main entrypoints, the API also provides a mechanism to register extensions via the Asciidoctor::Extensions API. To learn more about extensions, see Extensions.

Load AsciiDoc using the API

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.

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

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

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"

You can also inspect all the document attributes:

pp doc.attributes

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}>

If you’re starting with a source String instead of a source file, you’d use the load method instead:

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

Once you have loaded the document, you can convert it by calling the convert method:

doc.convert

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

Convert AsciiDoc using the API

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.

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

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

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'

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

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

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.

If you’re starting with a source String instead of a source file, you’d use the convert method instead:

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

In this case, embedded HTML is returned. To instruct Asciidoctor to write standalone HTML to a file instead, the :to_file option is mandatory.

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

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