Asciidoctor PDF is a native PDF renderer for AsciiDoc. We’re talking AsciiDoc straight to PDF!
Project statusAsciidoctor 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.
Direct AsciiDoc to PDF conversion
Configuration-driven style and layout
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)
Orphan section titles avoided
Table border settings honored
Font-based icons (currently admonition blocks only)
All that’s needed is Ruby (1.9.3 or better; 2.2.x recommended) and a few Ruby Gems, 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
You can get Asciidoctor PDF by installing the published gem.
Asciidoctor PDF is published in pre-release on RubyGems.org. You can install the published gem 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 -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 use the example.adoc file found in the examples directory of the Asciidoctor PDF repository.
= Document Title Doc Writer <firstname.lastname@example.org> :doctype: book :source-highlighter: coderay :listing-caption: Listing // Uncomment next line to set page size (default is Letter) //:pdf-page-size: A4 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.
You’ll need to 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 example.adoc
This command is just a shorthand way of running:
$ asciidoctor -r asciidoctor-pdf -b pdf example.adoc
When the script completes, you should see the file example.pdf in the same directory. Open the example.pdf file with a PDF viewer to see the result.
You’re also encouraged to try rendering 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.
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.
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.
Copyright © 2014 OpenDevise Inc. and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.