Lo and behold, a native PDF converter for AsciiDoc built with Asciidoctor and Prawn!
No more DocBook toolchain.
No more middleman.
It’s just AsciiDoc straight to PDF!
|
Caution
|
Project status
Asciidoctor PDF is currently alpha software.
Use accordingly.
Though the bulk of AsciiDoc content is converter, there’s still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented.
Once it’s ready, the project will be moved into the Asciidoctor organization on GitHub.
|
Asciidoctor PDF is made possible by the amazing Prawn RubyGem. 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 accomodate 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.
To give you a picture, here’s an example that shows how to use Prawn to create a basic PDF document.
require 'prawn'
Prawn::Document.generate 'example.pdf' do
text 'Hello, PDF creation!'
endIt’s that easy. And it’s just the beginning.
Simply put, 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 printable documents from AsciiDoc.
-
Direct AsciiDoc to PDF conversion
-
Configuration-driven style and layout
-
PDF document outline (i.e., bookmarks)
-
Document metadata (title, authors, subject, keywords, etc)
-
Internal cross reference links
-
Syntax highlighting with CodeRay or Pygments
-
Page breaks avoided in block content
-
Orphan section titles avoided
-
Table border settings honored
See WORKLOG.
All that’s needed is Ruby 1.9.3 or better (2.1.2 recommended) and a few RubyGems, which we explain how to install in the next section.
To check you have Ruby available, use the ruby command to query the version installed:
$ ruby --version
If you’re using RVM, we recommend creating a new gemset to work with Asciidoctor and Asciidoctor PDF:
$ rvm use 2.1@asciidoctor-pdf --create
We like RVM because it keeps the dependencies required by various projects isolated.
The Asciidoctor PDF project is published in pre-release on RubyGems.org. You can either install the pre-release version using the following command:
$ gem install --pre asciidoctor-pdf
If you want to syntax highlight source listings, you’ll also want to install CodeRay or Pygments. To be safe, go ahead and install both gems:
$ gem install coderay pygments.rb
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!
Skip ahead to the Example AsciiDoc document section to start putting Asciidoctor PDF to use. Alternatively, you can follow the steps below to install the project from source.
You can retrieve the Asciidoctor PDF project in one of two ways:
-
Clone the git repository
-
Download a zip archive of the repository
If you want to clone the git repository, simply copy the GitHub repository URL and pass it to git clone command:
$ git clone https://github.com/asciidoctor/asciidoctor-pdf
Next, change to the project directory:
$ cd asciidoctor-pdf
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.
|
Tip
|
Instead of working out of the asciidoctor-pdf directory, you can simply add the absolute path of the bin directory to your PATH environment variable. |
We’ll leverage the project configuration to install the necessary dependencies.
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 version installed:
$ 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:
$ bundle
Assuming all the required gems install properly, verify you can run the asciidoctor-pdf script using Ruby:
$ ruby ./bin/asciidoctor-pdf -v
If you see the version of Asciidoctor PDF printed, you’re ready to use Asciidoctor PDF! If you do get an error message and installed using Bundler, use
$ bundle exec ./bin/asciidoctor-pdf -v
to verify that you can use Asciidoctor PDF. You need to call Bundler from the project directory so that it can find the Gemfile.
Let’s grab an AsciiDoc document to distill.
If you don’t already have an AsciiDoc document, you can use the example.adoc file found in the examples directory of this project.
= Document Title
Doc Writer <doc@example.com>
:doctype: book
:source-highlighter: coderay
:listing-caption: Listing
A simple http://asciidoc.org[AsciiDoc] document.
== Introduction
A paragraph followed by a simple list with square bullets.
[square]
* item 1
* item 2
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
----It’s time to convert the AsciiDoc document directly to PDF.
Converting to PDF is a simple as running the ./bin/asciidoctor-pdf script using Ruby and passing our AsciiDoc document as the first argument.
$ ruby ./bin/asciidoctor-pdf example.adoc
When the script completes, you should see the file example.pdf in the same directory.
|
Important
|
You’ll need to the coderay gem installed to run this example since it uses the source-highlighter attribute with the value of coderay.
|
Open the 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. Another good example is the CDI Specification.
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.
See the files default-theme.yml and asciidoctor-theme.yml found in the data/themes directory for examples.
Specify the path to an alternate theme file with the pdf-style attribute. For example to use the built-in asciidoctor theme:
$ ./bin/asciidoctor-pdf -a pdf-style=asciidoctor examples/example.adoc
To refer to a theme at another location you can use the pdf-stylesdir attribute to specify the location of themes.
If the pdf-style value does not end in .yml, then the file name is calculated as {pdf-style}-theme.yml located in the pdf-stylesdir directory (which defaults to the built-in data/themes directory).
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 example.pdf
The command will generate the file example-optimized.pdf in the current directory.
|
Warning
|
The optimize-pdf script currently requires a Bash shell (Linux, OSX, etc). We plan to rewrite the script in Ruby so it works across platforms (see issue #1) |
|
Important
|
The optimize-pdf script relies on Ghostscript >= 9.10. Otherwise, it may actually make the PDF larger. Also, you should only consider using it if the file size of the original PDF is > 5MB. |
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.
Feel free to use the issue tracker or Asciidoctor mailing list to provide feedback or suggestions in other ways.
Asciidoctor PDF was written by Dan Allen and Sarah White of OpenDevise Inc. on behalf of the Asciidoctor Project.