Asciidoctor Ruby API Overview

In addition to its CLI, Asciidoctor provides a Ruby API. The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.

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'

Now you can start processing AsciiDoc documents. 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.