|Asciidoctor PDF is currently alpha software. While the converter handles most AsciiDoc content, there’s still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented. See the milestone v1.5.0 in the issue tracker for details.|
Prawn, the majestic PDF generator
Asciidoctor PDF is made possible by an amazing Ruby gem named Prawn. And what a gem it is!
Prawn is a nimble PDF writer for Ruby. More important, it’s a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accommodate special circumstances.
With Prawn, you can write text, draw lines and shapes and place images anywhere on the page and add as much color as you like. In addition, it brings a fluent API and aggressive code re-use to the printable document space.
Here’s an example that demonstrates how to use Prawn to create a basic PDF document.
require 'prawn' Prawn::Document.generate 'output.pdf' do text 'Hello, PDF creation!' end
It’s that easy. And that’s just the beginning. Skip ahead to Getting started to start putting it use.
Prawn is the killer library for PDF generation we’ve needed to close this critical gap in Asciidoctor. It absolutely takes the pain out of creating printable documents. Picking up from there, Asciidoctor PDF takes the pain out of creating PDF documents from AsciiDoc.
Direct AsciiDoc to PDF conversion
PDF document outline (i.e., bookmarks)
Table of contents page(s)
Document metadata (title, authors, subject, keywords, etc)
Internal cross reference links
Syntax highlighting with CodeRay or Pygments
Customizable running content (header and footer)
“Keep together” blocks (i.e., page breaks avoided in certain block content)
Autofit verbatim blocks (as permitted by base_font_size_min setting)
Orphan section titles avoided
Table border settings honored
All that’s needed is Ruby (1.9.3 or above; 2.2.x recommended) and a few Ruby gems, which we explain how to install in the next section.
To check if you have Ruby available, use the
ruby command to query the version installed:
$ ruby --version
Prawn 2.0.0 and above requires Ruby >= 2.0.0 at installation (though it still works with Ruby 1.9.3 once you get beyond installation). If you need to use Asciidoctor PDF with Ruby 1.9.3, you must first install Prawn 1.3.0 using:
You can then proceed with installation of Asciidoctor PDF.
Asciidoctor assumes you’re using UTF-8 encoding. To minimize encoding problems, make sure the default encoding of your system is set to UTF-8.
If you’re using a non-English Windows environment, the default encoding of your system may not be UTF-8.
As a result, you may get an
Encoding::UndefinedConversionError or other encoding issues when invoking Asciidoctor.
To solve these problems, we recommend at least changing the active code page in your console to UTF-8.
Once you make this change, all your Unicode headaches will be behind you.
Install the published gem
Asciidoctor PDF is published as a pre-release on RubyGems.org. You can install the published gem using the following command:
$ gem install asciidoctor-pdf --pre
If you want to syntax highlight source listings, you’ll also want to install CodeRay, Rouge or Pygments. Choose one (or more) of the following:
$ gem install coderay
$ gem install rouge
$ gem install pygments.rb
You then activate syntax highlighting for a given document by adding the
source-highlighter attribute to the document header (CodeRay shown):
Assuming all the required gems install properly, verify you can run the
$ 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!
An example AsciiDoc document
If you don’t already have an AsciiDoc document, you can use the basic-example.adoc file found in the examples directory of this project.
It’s time to convert the AsciiDoc document directly to PDF.
Convert AsciiDoc to PDF
You’ll need the
Converting to PDF is a simple as running the
asciidoctor-pdf script using Ruby and passing our AsciiDoc document as the first argument.
$ asciidoctor-pdf basic-example.adoc
This command is just a shorthand way of running:
$ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc
asciidoctor-pdf command just saves you from having to remember all those flags.
That’s why we created it.
When the script completes, you should see the file basic-example.pdf in the same directory. Open the basic-example.pdf file with a PDF viewer to see the result.
You’re also encouraged to try converting this README as well as the documents in the examples directory to see more of what Asciidoctor PDF can do.
The pain of the DocBook toolchain should be melting away about now.
The layout and styling of the PDF is driven by a YAML configuration file. To learn how the theming system works and how to create and apply custom themes, refer to the Asciidoctor PDF Theme Guide. You can use the built-in theme files, which you can find in the data/themes directory, as examples.
You can use icons in your PDF document using any of the following icon sets:
You can enable font-based icons by setting the following attribute in the header of your document:
If you want to override the font set globally, also set the
:icons: font :icon-set: pf
Here’s an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence:
Available now at icon:amazon.
You can use the
set attribute on the icon macro to override the icon set for a given icon.
Available now at icon:amazon[set=pf].
In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc).
You can enable use of fonts during PDF generation (instead of in the document header) by passing the
icons attribute to the
$ asciidoctor-pdf -a icons=font -a icon-set=octicon sample.adoc
Icon-based fonts are handled by the
To find a complete list of available icons, consult the prawn-icon repository.
Asciidoctor PDF also provides a shell script that invokes GhostScript (
gs) to optimize and compress the generated PDF with minimal impact on quality.
You must have Ghostscript installed to use it.
Here’s an example usage:
$ ./bin/optimize-pdf basic-example.pdf
The command will generate the file example-optimized.pdf in the current directory.
If a file is found with the extension
.pdfmarks and the same rootname as the input file, it is used to add metadata to the generated PDF document.
This file is necessary to preserve the document metadata since Ghostscript will otherwise drop it.
That’s why Asciidoctor PDF always creates this file in addition to the PDF.
In the spirit of free software, everyone is encouraged to help improve this project.
To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
To help develop Asciidoctor PDF, or to simply use the development version, you need to get the source from GitHub. Follow the instructions below to learn how to clone the source and run it from your local copy.
Retrieve the source code
You can retrieve the source of Asciidoctor PDF in one of two ways:
Clone the git repository
Download a zip archive of the repository
Option 1: Fetch using git clone
If you want to clone the git repository, simply copy the GitHub repository URL and pass it to the
git clone command:
$ git clone https://github.com/asciidoctor/asciidoctor-pdf
Next, change to the project directory:
$ cd asciidoctor-pdf
Option 2: Download the archive
If you want to download a zip archive, click the Download Zip button on the right-hand side of the repository page on GitHub. Once the download finishes, extract the archive, open a console and change to that directory.
Instead of working out of the asciidoctor-pdf directory, you can simply add the absolute path of the bin directory to your
We’ll leverage the project configuration to install the necessary dependencies.
If you’re using RVM, we recommend creating a new gemset to work with Asciidoctor PDF:
$ rvm use 2.2@asciidoctor-pdf --create
We like RVM because it keeps the dependencies required by various projects isolated.
The dependencies needed to use Asciidoctor PDF are defined in the Gemfile at the root of the project. We can use Bundler to install the dependencies for us.
To check you have Bundler available, use the
bundle command to query the installed version:
$ bundle --version
If it’s not installed, use the
gem command to install it.
$ gem install bundler
Then use the
bundle command to install the project dependencies:
You need to call
Assuming all the required gems install properly, verify you can run the
asciidoctor-pdf script using Ruby:
$ ruby ./bin/asciidoctor-pdf -v
$ bundle exec ./bin/asciidoctor-pdf -v
If you see the version of Asciidoctor PDF printed, you’re ready to use Asciidoctor PDF!
If you get an error message—and you’re not using a Ruby manager like RVM—you may need to invoke the script through