Process AsciiDoc Using the API

In addition to its CLI, Asciidoctor provides a Ruby API. The API is intended for integration with other Ruby software, such as Rails, GitHub, and GitLab, as well as other languages, such as Java (via AsciidoctorJ) and JavaScript (via Asciidoctor.js).

Asciidoctor also has a Java API that mirrors the Ruby API. The Java API calls through to the Ruby API using an embedded JRuby runtime. See the AsciidoctorJ documentation for more information.

Load and convert a document using the API

To use Asciidoctor in your application, you first need to require the gem:

require 'asciidoctor'

This one statement makes all of the public APIs in Asciidoctor available to your script or application. Now you can start processing AsciiDoc documents. The main entry points in the Asciidoctor API are the static methods to load or convert AsciiDoc documents, which we’ll cover on this page.

To parse a file into an Asciidoctor::Document object:

doc = Asciidoctor.load_file 'my-sample.adoc'

You can get information about the document:

puts doc.doctitle
puts doc.attributes

To convert a file containing AsciiDoc markup to HTML 5, use:

Asciidoctor.convert_file 'my-sample.adoc'

The command will output to the file my-sample.html in the same directory.

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

Asciidoctor.convert_file 'my-sample.adoc', backend: 'docbook'

The command will output to the file my-sample.xml in the same directory.