== Getting Started

You can get _Asciidoctor PDF_ by installing the published gem or running the
code from source.

=== Install the Published Gem

_Asciidoctor PDF_ is published as a pre-release on RubyGems.org. First, make
sure you have satisfied the prerequisites. Then, you can install the published
gem using the following command:

[source, sh]
----
gem install asciidoctor-pdf --pre
----

If you want to syntax highlight source listings, you'll also want to install
Rouge, Pygments, or CodeRay. Choose one (or more) of the following:

.Rouge (preferred)
[source, sh]
----
gem install rouge
----

.Pygments
[source, sh]
----
gem install pygments.rb
----

.CodeRay
[source, sh]
----
gem install coderay
----

You then activate syntax highlighting for a given document by adding the
`source-highlighter` attribute to the document header (Rouge shown):

[source, asciidoc]
----
:source-highlighter: rouge
----

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

[source, sh]
----
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.

/////
ifeval::[{safe-mode-level} < 20]
.000_basic_example.adoc
[source, asciidoc]
----
= Document Title

Doc Writer <doc@example.com>
:doctype: book
:reproducible:
//:source-highlighter: coderay
:source-highlighter: rouge
:listing-caption: Listing
// Uncomment next line to set page size (default is A4)
//:pdf-page-size: Letter

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
----
endif::[]
/////

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

=== Convert AsciiDoc to PDF

IMPORTANT: 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 a simple as running the `asciidoctor-pdf` script using
_Ruby_ and passing our AsciiDoc document as the first argument.

[source, sh]
----
asciidoctor-pdf 000_basic_example.adoc
----

This command is just a *shorthand* way of running:

[source, sh]
----
asciidoctor -r asciidoctor-pdf -b pdf 000_basic_example.adoc
----

The `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 *000_basic_example.pdf*
in the same directory. Open the *000_basic_example.pdf* file with a PDF
viewer to see the result.

ifdef::backend-html5[]
.Example PDF document rendered in a PDF viewer
lightbox::images-example--pdf-screenshot[ 1024, {data-images-example--pdf-screenshot}, role="mb-4" ]
endif::[]

ifdef::backend-pdf[]
.Example PDF document rendered in a PDF viewer
image::/assets/images/pages/asciidoc_skeletons/example-pdf-screenshot.png[PDF document rendered in a PDF viewer, width=800, scaledwidth=100%]
endif::[]

You're also encouraged to try converting 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 from now.