asciidoctor-pdf 0,2,0 ruby Rubygems

:page_with_curl: Asciidoctor PDF: A native PDF renderer for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.

3 years after MIT

= Asciidoctor PDF: A native PDF converter for AsciiDoc Dan Allen https://github.com/mojavelinux[@mojavelinux]; Sarah White https://github.com/graphitefriction[@graphitefriction] // Settings: :experimental: :idprefix: :idseparator: - ifndef::env-github[:icons: font] ifdef::env-github,env-browser[] :toc: macro :toclevels: 1 endif::[] ifdef::env-github[] :status: :outfilesuffix: .adoc :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] // Aliases: :project-name: Asciidoctor PDF :project-handle: asciidoctor-pdf // URIs: :uri-asciidoctor: http://asciidoctor.org :uri-gem: http://rubygems.org/gems/asciidoctor-pdf :uri-project: https://github.com/asciidoctor/asciidoctor-pdf :uri-project-repo: {uri-project} :uri-project-issues: {uri-project-repo}/issues :uri-project-list: http://discuss.asciidoctor.org :uri-prawn: http://prawn.majesticseacreature.com :uri-rvm: http://rvm.io

ifdef::status[] image:https://img.shields.io/gem/v/asciidoctor-pdf.svg[Latest Release, link={uri-gem}] image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License, link=#copyright] endif::[]

Lo and behold, a native PDF converter for AsciiDoc built with {uri-asciidoctor}[Asciidoctor] and {uri-prawn}[Prawn]! + No more middleman. + No more DocBook toolchain. + It's AsciiDoc straight to PDF!

[caption=Status] CAUTION: {project-name} 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-project-issues}[issue tracker] for details.

toc::[]

== Prawn, the Majestic PDF Generator

{uri-project}[{project-name}] is made possible by an amazing Ruby gem named Prawn. And what a gem it is!

{uri-prawn}[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 accommodate 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.

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. Skip ahead to <<getting-started,Getting started>> to start putting it use.

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, {project-name} takes the pain out of creating PDF documents from AsciiDoc.

== Features

=== Notable Features

  • Direct AsciiDoc to PDF conversion
  • <<docs/theming-guide.adoc#,Configuration-driven style and layout>>
  • 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)

=== Missing Features

See <<WORKLOG.adoc#,WORKLOG>>.

== 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:

$ ruby --version

[WARNING]

By default, Asciidoctor PDF selects the latest version of Prawn to install. Since version 2.0.0, Prawn requires Ruby >= 2.0.0 during installation (though it may still work with Ruby 1.9.3 if you get past installation). Therefore, to use Asciidoctor PDF with Ruby 1.9.3, you must first explicitly install Prawn 1.3.0 and Prawn SVG 0.21.0 using the following commands:

$ gem install prawn --version 1.3.0 gem install prawn-svg --version 0.21.0

You can then proceed with installation of Asciidoctor PDF on Ruby 1.9.3.

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

== Getting Started

You can get {project-name} by <<install-the-published-gem,installing the published gem>> or <<development,running the code from source>>.

=== Install the Published Gem

{project-name} is published as a pre-release on RubyGems.org. You can install the published gem using the following command:

$ gem install asciidoctor-pdf --pre

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

.CodeRay $ gem install coderay

.Rouge $ gem install rouge

.Pygments $ gem install pygments.rb

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

[source,asciidoc]

:source-highlighter: coderay

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

$ asciidoctor-pdf -v

If you see the version of {project-name} printed, you're ready to use {project-name}.

Let's grab an AsciiDoc document to distill and start putting {project-name} to use!

=== An Example AsciiDoc Document

If you don't already have an AsciiDoc document, you can use the [file]basic-example.adoc file found in the examples directory of this project.

ifeval::[{safe-mode-level} >= 20] See <<examples/basic-example.adoc#,basic-example.adoc>>. endif::[] ifeval::[{safe-mode-level} < 20] .basic-example.adoc [source,asciidoc] .... include::examples/basic-example.adoc[] .... 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.

$ asciidoctor-pdf basic-example.adoc

This command is just a shorthand way of running:

$ asciidoctor -r asciidoctor-pdf -b pdf 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 [file]basic-example.pdf in the same directory. Open the [file]basic-example.pdf file with a PDF viewer to see the result.

.Example PDF document rendered in a PDF viewer image::examples/example-pdf-screenshot.png[Screenshot of PDF document,width=800,scaledwidth=100%]

You're also encouraged to try converting this <<README#,README>> as well as the documents in the examples directory to see more of what {project-name} can do.

The pain of the DocBook toolchain should be melting away about now.

== Themes

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 <<docs/theming-guide.adoc#,Asciidoctor PDF Theme Guide>>. You can use the built-in theme files, which you can find in the [file]data/themes directory, as examples.

== Font-Based Icons

You can use icons in your PDF document using any of the following icon sets:

You can enable font-based icons by setting the following attribute in the header of your document:

[source,asciidoc]

:icons: font

If you want to override the font set globally, also set the icon-set attribute:

[source,asciidoc]

:icons: font :icon-set: pf

Here's an example that shows how to use the Amazon icon from the payment font (pf) icon set in a sentence:

[source,asciidoc]

Available now at icon:amazon[].

You can use the set attribute on the icon macro to override the icon set for a given icon.

[source,asciidoc]

Available now at icon:amazon[set=pf].

In addition to the sizes supported in the HTML backend (lg, 1x, 2x, etc), you can enter any relative value in the size attribute (e.g., 1.5em, 150%, etc).

[source,asciidoc]

icon:android[size=40em]

You can enable use of fonts during PDF generation (instead of in the document header) by passing the icons attribute to the asciidoctor-pdf command.

$ asciidoctor-pdf -a icons=font -a icon-set=octicon sample.adoc

Icon-based fonts are handled by the prawn-icon gem. To find a complete list of available icons, consult the https://github.com/jessedoyle/prawn-icon/tree/master/data/fonts[prawn-icon] repository.

== Image Paths

Images are resolved relative to the value of the imagesdir attribute at the time the converter is run. This is effectively the same as how the built-in HTML converter works when the data-uri attribute is set. The imagesdir is blank by default, which means images are resolved relative to the input document.

If the image is an SVG, and the SVG includes a nested raster image (png or jpg) with a relative path, that path is resolved relative to the directory that contains the SVG.

The converter will refuse to include an image if the target is a URI unless the allow-uri-read attribute is enabled via the CLI or API.

== Image Scaling

Since PDF is a fixed-width canvas, you almost always need to specify a width to get the image to fit properly on the page. There are five ways to specify the width of an image, listed here in order of precedence:

[cols="1s,3d"] |=== |Attribute{nbsp}Name | Description

|pdfwidth |The display width of the image as an absolute size (e.g., 2in), percentage of the content area width (e.g., 75%), or percentage of the page width (e.g., 100vw). Intended to be used for the PDF converter only.

|scaledwidth |The display width of the image as a percentage of the content area width (e.g., 75%). Intended to be used for print output such as PDF.

|image_width key from theme |Accepts the same values as pdfwidth. Only applies to block images.

|width |The unitless display width of the image (assumed to be pixels), typically matching the intrinsic width of the image. If the width exceeds the content area width, the image is scaled down to the content area width.

|unspecified |If you don't specify one of the aforementioned width settings, the intrinsic width of the image is used (the px value is multiplied by 75% to convert to pt) unless the width exceeds the content area width, in which case the image is scaled down to the content area width. |===

The image is always sized according to the explicit or intrinsic width and its height is scaled proporationally. The height of the image is ignored by the PDF converter unless the height of the image exceeds the content height of the page. In this case, the image is scaled down to fit on a single page.

=== Using the pdfwidth Attribute

The pdfwidth attribute is the recommended way to set the image size for the PDF output. This attribute is provided for two reasons. First, the fixed-width canvas often calls for a width that is distinct from other output formats, such as HTML. Second, this attribute allows the width to be expressed using a variety of units.

The pdfwidth attribute supports the following units:

  • pt (default)
  • in
  • cm
  • mm
  • px
  • vw (percentage of page width)
  • % (percentage of content area width)

In all cases, the width is converted to pt.

=== Specifying a default pdfwidth

If you want to scale all block images that don't have a pdfwidth (or scaledwidth) attribute the same, assign a value to the image_width key in your theme.

[source,yaml]

image: width: 100%

=== Inline Image Sizing

Inline images are handled different than block images. In particular, inline images do not support sizing using the pdfwidth attribute.

Here's how an inline image is sized. The image height is scaled down to 75% of the specified width (px to pt conversion). If the image height is more than 1.5x the height of the surrounding line of text, the font size and line metrics of the fragment are modified to fit the image in the line.

== Printing

To print a range of pages as labeled in the document, you need to add the number of front matter pages (the pages labeled with a roman numeral) to the printed page number(s). The print dialog doesn't understand the page numbers labels. Instead, it only considers the physical pages.

== Optional Scripts

{project-name} 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 basic-example.pdf

The command will generate the file [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 https://github.com/asciidoctor/asciidoctor-pdf/issues/1[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 .pdfmark 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 {project-name} always creates this file in addition to the PDF.

== Contributing

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 {uri-project-issues}[issue tracker] or {uri-project-list}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.

== Development

To help develop {project-name}, or to simply use the development version, you need to get the source from GitHub. Follow the instructions below to learn how to clone the source and run it from your local copy.

=== Retrieve the Source Code

You can retrieve the source of {project-name} in one of two ways:

. Clone the git repository . Download a zip archive of the repository

==== Option 1: Fetch Using Git

If you want to clone the git repository, simply copy the {uri-project-repo}[GitHub repository URL] and pass it to the git clone command:

$ git clone https://github.com/asciidoctor/asciidoctor-pdf

Next, change to the project directory:

$ cd asciidoctor-pdf

==== Option 2: Download the Archive

If you want to download a zip archive, click the btn:[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 {project-handle} directory, you can simply add the absolute path of the [path]bin directory to your PATH environment variable.

We'll leverage the project configuration to install the necessary dependencies.

=== Install Dependencies

If you're using {uri-rvm}[RVM], we recommend creating a new gemset to work with {project-name}:

$ rvm use [email protected] --create

We like RVM because it keeps the dependencies required by various projects isolated.

The dependencies needed to use {project-name} are defined in the [file]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 installed version:

$ 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

NOTE: You need to call bundle from the project directory so that it can find the [file]Gemfile.

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

$ bundle exec ./bin/asciidoctor-pdf -v

If you see the version of {project-name} printed, you're ready to use {project-name}!

CAUTION: If you get an error message--and you're not using a Ruby manager like RVM--you may need to invoke the script through bundle exec: For best results, be sure to always use bundle exec whenever invoking the ./bin/asciidoctor-pdf script in development mode.

[[resources,Links]] == Resources

== Authors

{project-name} was written by https://github.com/mojavelinux[Dan Allen] and https://github.com/graphitefriction[Sarah White] of OpenDevise Inc. on behalf of the Asciidoctor Project.

== Copyright

Copyright (C) 2014-2016 OpenDevise Inc. and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

For the full text of the license, see the <<LICENSE.adoc#,LICENSE>> file. Refer to the <<NOTICE.adoc#,NOTICE>> file for information about third-party Open Source software in use.

Related Repositories

asciidoctorj

asciidoctorj

:coffee: Java bindings for Asciidoctor. Asciidoctor on the JVM! ...

asciidoctor-fopub

asciidoctor-fopub

A portable DocBook-to-PDF build command that wraps DocBook XSL and Apache FOP ...

asciidoctor-gradle-examples

asciidoctor-gradle-examples

A collection of example projects that demonstrates how to use the Asciidoctor Gr ...

eBook-Template

eBook-Template

Template to create PDF, ePub and Kindle books with Asciidoctor ...

asciidoctor-maven-examples

asciidoctor-maven-examples

A collection of example projects that demonstrates how to use the Asciidoctor Ma ...


Top Contributors

mojavelinux DavidGamba jessedoyle leif81 theimdal nawroth abatalev meisterluk gregturn arteam erik-brangs fwilhe fredkelly AlexanderZobkov gliptak vogella LightGuard mgreau ntfc otavio chloerei graphitefriction stephenhay anandchida bk2204 olegsmetanin orthographic-pedant

Releases

-   v1.5.0.alpha.13 zip tar
-   v1.5.0.alpha.12 zip tar
-   v1.5.0.alpha.11 zip tar
-   v1.5.0.alpha.10 zip tar
-   v1.5.0.alpha.9 zip tar
-   v1.5.0.alpha.8 zip tar
-   v1.5.0.alpha.7 zip tar
-   v1.5.0.alpha.6 zip tar
-   v1.5.0.alpha.5 zip tar
-   v1.5.0.alpha.4 zip tar
-   v1.5.0.alpha.3 zip tar
-   v1.5.0.alpha.2 zip tar
-   v1.5.0.alpha.1 zip tar