Convert AsciiDoc to PDF

Run Asciidoctor PDF

Assuming all the required gems install properly, verify you can run the asciidoctor-pdf command:

$ asciidoctor-pdf -v

If you see the version of Asciidoctor PDF printed, you’re ready to use Asciidoctor PDF!

Let’s grab an AsciiDoc document to distill and start putting Asciidoctor PDF to use. If you don’t already have an AsciiDoc document, you can download and use the Basic Example AsciiDoc file. Store the file in the current directory.

Let’s take a look at the contents of that file.

basic-example.adoc

= Document Title
Doc Writer <doc@example.com>
:reproducible:
:listing-caption: Listing
:source-highlighter: rouge
:toc:
// Uncomment next line to add a title page (or set doctype to book)
//:title-page:
// Uncomment next line to set page size (default is A4)
//:pdf-page-size: Letter

An example of a basic https://asciidoc.org[AsciiDoc] document prepared by {author}.

== Introduction

A paragraph followed by an unordered list{empty}footnote:[AsciiDoc supports unordered, ordered, and description lists.] with square bullets.footnote:[You may choose from square, disc, and circle for the bullet style.]

[square]
* item 1
* item 2
* item 3

== Main

Here's how you say "`Hello, World!`" in Prawn:

.Create a basic PDF document using Prawn
[source,ruby]
----
require 'prawn'

Prawn::Document.generate 'example.pdf' do
  text 'Hello, World!'
end
----

== Conclusion

That's all, folks!

It’s time to convert the AsciiDoc document directly to PDF.

Convert an AsciiDoc document to PDF

You’ll need the rouge gem installed to run this example since it uses the source-highlighter attribute with the value of rouge.

Converting to PDF is as straightforward as running the asciidoctor-pdf command using Ruby and passing the AsciiDoc document as the first argument:

$ asciidoctor-pdf basic-example.adoc

This command is a shorter way of running asciidoctor with the PDF converter and backend enabled:

$ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc

The asciidoctor-pdf command saves you from having to remember these low-level options. That’s why we provide it.

When the command completes, you should see the file basic-example.pdf in the current directory. Asciidoctor creates the output file in the same directory as the input file by default. Open the basic-example.pdf file with a PDF viewer to see the result.

Figure 1. Example PDF document rendered in a PDF viewer

Notice that the body of the document is arranged in a single column. If the doctype is set to article (the default) or manpage, the body of the document can be arranged into multiple columns by assigning a column count to the page-columns key in a custom theme. The width of the gap between the columns can be adjusted using the page-column-gap theme key. See Page Columns for more information about how to activate this feature.

Convert to PDF using the API

In addition to the asciidoctor-pdf command, you can convert to PDF using the Asciidoctor API. The selection of the Asciidoctor PDF converter is controlled through use of the backend keyword, which may be specified either as an API option or a document attribute.

First, make sure you have the Asciidoctor PDF gem installed and available on the Ruby runtime path. Once that step is complete, require the asciidoctor-pdf gem to load the Asciidoctor PDF converter.

require 'asciidoctor-pdf'

You can now use the main Asciidoctor API to convert an AsciiDoc document to PDF.

require 'asciidoctor-pdf'

Asciidoctor.convert_file 'basic-example.adoc', backend: 'pdf', safe: :unsafe

This API call is equivalent to the command shown in the previous section. The script first requires the asciidoctor-pdf gem (equivalent to -r asciidoctor-pdf). Then it invokes Asciidoctor with the safe mode set to unsafe (equivalent to the asciidoctor command) and the backend to pdf (equivalent to -b pdf). You can run this script using the ruby command.

When the script completes, you should see the file basic-example.pdf in the current directory. You can use the typical set of API options to customize where this file is written.

If you use the convert method instead of the convert_file method, Asciidoctor will return the instance of the converter (which is also an instance of Prawn::Document). If you want to capture the PDF stream, you need to do so by redirecting the output to a StringIO object.

require 'asciidoctor-pdf'
require 'stringio'

Asciidoctor.convert 'I *love* AsciiDoc!', backend: 'pdf', safe: :unsafe, to_file: (pdf = StringIO.new)
puts pdf.string

You can also capture the PDF strea after the fact by passing the returned document to the write method on that same object.

require 'asciidoctor-pdf'
require 'stringio'

doc = Asciidoctor.convert 'I *love* AsciiDoc!', backend: 'pdf', safe: :unsafe
doc.write doc, (pdf = StringIO.new)
puts pdf.string

This call is the equivalent to the following:

require 'asciidoctor-pdf'
require 'stringio'

puts (Asciidoctor.convert 'I *love* AsciiDoc!', backend: 'pdf', safe: :unsafe).render

The main difference is that calling render directly on the returned converter object does not trigger the cleanup routine, which is important when converting to PDF. Thus, using a StringIO object as the target is preferable.