Asciidoctor PDF is a native PDF converter for AsciiDoc that plugs into
the PDF backend. It bypasses the requirement to generate an intermediary
format such as DocBook, Apache FO, or LaTeX. Instead, you can use Asciidoctor
PDF to convert your documents directly from AsciiDoc to PDF. The aim of
this library is to take the pain out of creating PDF documents from AsciiDoc.

{uri-asciidoctor-pdf}[Asciidoctor PDF, {browser-window--new}] is made possible
by an amazing Ruby gem named _Prawn_. And what a gem it is!
{uri-prawn-home}[Prawn, {browser-window--new}] 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.

[CAUTION]
====
_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 {uri-asciidoctor-pdf-issues}[Issue tracker, {browser-window--new}]
for details.
====

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.

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

Prawn::Document.generate 'output.pdf' do
  text 'Hello, PDF creation!'
end
----

It's that easy.
And that's just the beginning.

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


[role="mt-5"]
== Highlights

* Direct AsciiDoc to PDF conversion
* SVG support
* 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 Rouge, Pygments, or CodeRay
* Page numbering
* Customizable running content (header and footer)
* “Keep together” blocks (i.e., page breaks avoided in certain block content)
* Orphaned section titles avoided
* Autofit verbatim blocks (as permitted by base_font_size_min setting)
* Table border settings honored
* Font-based icons
* Custom (TTF) fonts
* Double-sided printing mode (margins alternate on recto and verso pages)


[role="mt-5"]
== Prerequisites

All that's needed is _Ruby_ (1.9.3 or above; 2.3.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:

[source, sh]
----
ruby --version
----

[WARNING]
====
By default, _Asciidoctor PDF_ automatically installs the latest version of _Prawn_
if you don't already have _Prawn_ installed. This will fail on older versions of
_Ruby_. To workaround, you need to install certain dependencies first.

Starting with _Prawn_ 2.0.0, _Prawn_ requires Ruby >= 2.0.0 during installation.
Therefore, to use _Asciidoctor PDF_ with Ruby 1.9.3, you must first explicitly
install the following dependencies to lock the versions:

[source, sh]
----
gem install prawn --version 1.3.0
gem install addressable --version 2.4.0
gem install prawn-svg --version 0.21.0
gem install prawn-templates --version 0.0.3
----

You can then proceed with installation of _Asciidoctor PDF_ on Ruby 1.9.3.

Starting with _Prawn_ 2.2.0, _Prawn_ requires Ruby >= 2.1.0 during installation.
Therefore, to use _Asciidoctor PDF_ with Ruby 2.0.0, you must first explicitly
install the following dependencies to lock the versions:

[source, sh]
----
gem install prawn --version 2.1.0
gem install prawn-svg --version 0.26.0
gem install prawn-templates --version 0.0.4
----

For all other versions of _Ruby_, you can simply install the _Asciidoctor PDF_
gem. It will transitively install the required dependencies.
====

[role="mt-4"]
=== System Encoding

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

 chcp 65001

Once you make this change, all your Unicode headaches will be behind you.