How to install and configure Asciidoctor PDF

What is AsciiDoc

From asciidoc.org

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

asciidoc.org

What is AsciiDoctor

Asciidoctor is a fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats. Asciidoctor is written in Ruby and runs on all major operation systems. To simplify installation, Asciidoctor is packaged and distributed as a gem to RubyGems.org and is packaged for popular Linux distributions and macOS.

asciidoctor.org

What is Asciidoctor PDF

Lo and behold, a native PDF converter for AsciiDoc built with Asciidoctor and Prawn!
No more middleman.
No more DocBook toolchain.
It’s AsciiDoc straight to PDF!

https://github.com/asciidoctor/asciidoctor-pdf

How to Install Asciidoctor PDF

$ sudo apt install ruby
.
.
.
$ ruby --version
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux-gnu]

$ sudo gem install asciidoctor-pdf --pre
 
Fetching: asciidoctor-2.0.2.gem (100%)
 Successfully installed asciidoctor-2.0.2
 Fetching: pdf-core-0.7.0.gem (100%)
 Successfully installed pdf-core-0.7.0
 Fetching: ttfunk-1.5.1.gem (100%)
 Successfully installed ttfunk-1.5.1
 Fetching: prawn-2.2.2.gem (100%)
 Successfully installed prawn-2.2.2
 Fetching: prawn-table-0.2.2.gem (100%)
 Successfully installed prawn-table-0.2.2
 Fetching: Ascii85-1.0.3.gem (100%)
 Successfully installed Ascii85-1.0.3
 Fetching: ruby-rc4-0.1.5.gem (100%)
 Successfully installed ruby-rc4-0.1.5
 Fetching: hashery-2.1.2.gem (100%)
 Successfully installed hashery-2.1.2
 Fetching: afm-0.2.2.gem (100%)
 Successfully installed afm-0.2.2
 Fetching: pdf-reader-2.2.0.gem (100%)
 Successfully installed pdf-reader-2.2.0
 Fetching: prawn-templates-0.1.1.gem (100%)
 Successfully installed prawn-templates-0.1.1
 Fetching: public_suffix-3.0.3.gem (100%)
 Successfully installed public_suffix-3.0.3
 Fetching: addressable-2.6.0.gem (100%)
 Successfully installed addressable-2.6.0
 Fetching: css_parser-1.7.0.gem (100%)
 Successfully installed css_parser-1.7.0
 Fetching: prawn-svg-0.27.1.gem (100%)
 Successfully installed prawn-svg-0.27.1
 Fetching: prawn-icon-1.3.0.gem (100%)
 Successfully installed prawn-icon-1.3.0
 Fetching: safe_yaml-1.0.5.gem (100%)
 Successfully installed safe_yaml-1.0.5
 Fetching: thread_safe-0.3.6.gem (100%)
 Successfully installed thread_safe-0.3.6
 Fetching: polyglot-0.3.5.gem (100%)
 Successfully installed polyglot-0.3.5
 Fetching: treetop-1.5.3.gem (100%)
 Successfully installed treetop-1.5.3
 Fetching: asciidoctor-pdf-1.5.0.alpha.16.gem (100%)
 Successfully installed asciidoctor-pdf-1.5.0.alpha.16
 Parsing documentation for asciidoctor-2.0.2
 Installing ri documentation for asciidoctor-2.0.2
 Parsing documentation for pdf-core-0.7.0
 Installing ri documentation for pdf-core-0.7.0
 Parsing documentation for ttfunk-1.5.1
 Installing ri documentation for ttfunk-1.5.1
 Parsing documentation for prawn-2.2.2
 Installing ri documentation for prawn-2.2.2
 Parsing documentation for prawn-table-0.2.2
 Installing ri documentation for prawn-table-0.2.2
 Parsing documentation for Ascii85-1.0.3
 Installing ri documentation for Ascii85-1.0.3
 Parsing documentation for ruby-rc4-0.1.5
 Installing ri documentation for ruby-rc4-0.1.5
 Parsing documentation for hashery-2.1.2
 Installing ri documentation for hashery-2.1.2
 Parsing documentation for afm-0.2.2
 Installing ri documentation for afm-0.2.2
 Parsing documentation for pdf-reader-2.2.0
 Installing ri documentation for pdf-reader-2.2.0
 Parsing documentation for prawn-templates-0.1.1
 Installing ri documentation for prawn-templates-0.1.1
 Parsing documentation for public_suffix-3.0.3
 Installing ri documentation for public_suffix-3.0.3
 Parsing documentation for addressable-2.6.0
 Installing ri documentation for addressable-2.6.0
 Parsing documentation for css_parser-1.7.0
 Installing ri documentation for css_parser-1.7.0
 Parsing documentation for prawn-svg-0.27.1
 Installing ri documentation for prawn-svg-0.27.1
 Parsing documentation for prawn-icon-1.3.0
 Installing ri documentation for prawn-icon-1.3.0
 Parsing documentation for safe_yaml-1.0.5
 Installing ri documentation for safe_yaml-1.0.5
 Parsing documentation for thread_safe-0.3.6
 Installing ri documentation for thread_safe-0.3.6
 Parsing documentation for polyglot-0.3.5
 Installing ri documentation for polyglot-0.3.5
 Parsing documentation for treetop-1.5.3
 Installing ri documentation for treetop-1.5.3
 invalid options: -ri
 (invalid options are ignored)
 Parsing documentation for asciidoctor-pdf-1.5.0.alpha.16
 Installing ri documentation for asciidoctor-pdf-1.5.0.alpha.16
 Done installing documentation for asciidoctor, pdf-core, ttfunk, prawn, prawn-table, Ascii85, ruby-rc4, hashery, afm, pdf-reader, prawn-templates, public_suffix, addressable, css_parser, prawn-svg, prawn-icon, safe_yaml, thread_safe, polyglot, treetop, asciidoctor-pdf after 34 seconds
 21 gems installed
 
$ asciidoctor-pdf -v
 Asciidoctor PDF 1.5.0.alpha.16 using Asciidoctor 2.0.2 [https://asciidoctor.org]
 Runtime Environment (ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

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:

$ sudo gem install rouge
 Fetching: rouge-3.3.0.gem (100%)
 Successfully installed rouge-3.3.0
 Parsing documentation for rouge-3.3.0
 Installing ri documentation for rouge-3.3.0
 Done installing documentation for rouge after 12 seconds
 1 gem installed
 $

You then activate syntax highlighting for a given document by adding the source-highlighter attribute to the document header

:source-highlighter: rouge

An Example

create your .adoc file and pass its name to the asciidoc-pdf command as first argument.

Create basic-example.adoc with content as below:

= 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

then run the command.

$  asciidoctor-pdf basic-example.adoc