Convert AsciiDoc to PDF

Run Asciidoctor PDF

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

$ 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.

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

An example of a basic[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.]

* item 1
* item 2
* item 3

== Main

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

.Create a basic PDF document using Prawn
require 'prawn'

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

== Conclusion

That's all, folks!

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

Convert an AsciiDoc document to a 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 script 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 script 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.

Screenshot of PDF document
Figure 1. Example PDF document rendered in a PDF viewer