1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
= Install Asciidoctor PDF
:url-rvm: https://rvm.io
On this page, you'll learn how to install Asciidoctor PDF.
The page documents the prerequisites you'll need, the command you'll use to install Asciidoctor PDF, and a catalog of optional dependencies you can install to unlock additional features.
You can also find some troubleshooting advice if the installation goes wrong.
[#prerequisites]
== Prerequisites
Asciidoctor PDF is a Ruby application.
Therefore, to use it, you'll need a Ruby runtime.
The Ruby versions on which Asciidoctor PDF is supported {url-project-repo}/blob/{page-origin-refname}/.github/workflows/ci.yml[and tested] are Ruby 2.7 or greater or JRuby 9.2 or greater.
We always recommend using the most recent version of Ruby or JRuby, if possible.
If you attempt to use an unsupported version of Ruby with Asciidoctor PDF, the conversion will likely fail in unexpected ways.
All required libraries (i.e., gems) will be installed automatically when you install Asciidoctor PDF, which is covered in the <<Install Asciidoctor PDF,next section>>.
You must install any <<optional-dependencies,optional dependencies>> yourself in order to activate the corresponding optional features.
To check if you have Ruby available, run the `ruby` command to print the installed version:
$ ruby -v
Make sure this command reports a Ruby version that starts with 2.7 (or a JRuby version that starts with 9.2).
If so, you're ready to proceed.
If not, head over to {url-rvm}[rvm.io^] to get RVM and use it to install Ruby.
=== 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.
See the xref:asciidoctor:install:supported-platforms.adoc#system-encoding[system encoding] requirements section to learn how to override the default character encodings when using Asciidoctor if you can't modify your system encoding.
== Install Asciidoctor PDF
Asciidoctor PDF (gem: *asciidoctor-pdf*, command: `asciidoctor-pdf`) is published as a RubyGem to the rubygems.org software registry.
You install Asciidoctor PDF from that registry using the RubyGem management tools provided by Ruby (`bundle` or `gem`).
Alternately, you can {url-project-repo}/blob/main/CONTRIBUTING-CODE.adoc[build and install Asciidoctor PDF from source^].
Refer to the table below for instructions on how to install Asciidoctor PDF.
If you use Bundler to manage your gems in a [.path]_Gemfile_, add the entry listed in the *Bundler* column.
Otherwise, run the command in the *gem command* column.
[%autowidth,cols=1h;1h;1l;1l]
|===
|Library |gem name |Bundler |gem command
|Asciidoctor PDF
|asciidoctor-pdf
|gem 'asciidoctor-pdf'
|gem install asciidoctor-pdf
|===
Installing Asciidoctor PDF will automatically install a number of additional gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk.
The versions of these required dependencies are locked to the version of Asciidoctor PDF.
[#prerelease]
=== Install a prerelease or development version
To install the latest prerelease of the *asciidoctor-pdf* gem from RubyGems.org (if a prerelease is available), use the following command:
$ gem install asciidoctor-pdf --pre
You can also {url-project-repo}/blob/main/CONTRIBUTING-CODE.adoc[run the code from source^] if you want to use a development version or participate in development.
[#troubleshooting]
== Installation troubleshooting
If you get a permission error while installing the gem, such as the one below, it's likely you're attempting to install the gem directly into your system.
Installing gems for tech writing directly into your system is not recommended.
.Permission error when attempting to install as a system gem
....
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.x.x directory.
....
A better practice (and one that will ensure your sanity) is to ignore any version of Ruby installed on your system and use {url-rvm}[RVM^] to manage the Ruby installation instead.
The benefit of this approach is that a) Ruby is guaranteed to be set up correctly, b) installing gems will in no way interfere with the operation of your system, and c) any bin scripts provided by the installed gems will be available on your PATH.
All files are managed in user space (aka your home or user directory).
If something gets messed up, you can simply remove the [.path]_$HOME/.rvm_ folder and start over.
To learn how to install RVM, follow the https://asciidoctor.org/docs/install-asciidoctor-macos/#rvm-procedure-recommended[RVM installation procedure^] covered in the Asciidoctor documentation.
//TODO determine best RVM instructions, if we still recommend, and put them in their proper home for xrefing to.
Once you have installed RVM, install a version of Ruby:
rvm install 3.1
Then switch to that version and set it as the default:
rvm use 3.1 --default
You only need to install the version of Ruby once.
Each time you open a new terminal, be sure to select the default Ruby.
rvm use default
After installing the asciidoctor-pdf gem, you can see where it was installed using the following command:
$ gem which asciidoctor-pdf
To see where the bin script is located, use this command:
$ command -v asciidoctor-pdf
Both paths should be underneath the [.path]_$HOME/.rvm_ directory.
If not, check your RVM setup.
[#optional-dependencies]
== Optional dependencies
There are several optional features of this converter that require additional gems to be installed.
Those features are as follows.
Source highlighting::
You'll need to xref:syntax-highlighting.adoc[install a syntax highlighter] to use source highlighting (build-time only).
PDF optimization::
If you want to optimize your PDF, you'll need rghost or hexapdf.
See xref:optimize-pdf.adoc[] for installation and usage instructions.
Automatic hyphenation::
To turn on automatic hyphenation using the `hyphens` attribute, you'll need to install the `text-hyphen` gem:
$ gem install text-hyphen
Accelerated image decoding::
Ruby is not particularly fast at decoding images, and the image formats it supports are limited.
To help, you can install prawn-gmagick, which delegates the work of decoding images to GraphicsMagick.
Refer to xref:image-paths-and-formats.adoc#other-image-formats[Supporting additional image file formats] for instructions about how to enable this integration.
The following table lists the optional dependencies of Asciidoctor PDF, including Asciidoctor extensions which are tested with this converter.
The name of the dependency and its gem name are listed along with the minimum supported version and what feature or features it enables when installed (and, if necessary, required).
.Minimum supported version of optional dependencies
[#table-minimum-version,cols=3;3;4]
|===
| Library / gem name | Minimum Version | Feature(s)
| *Asciidoctor Mathematical* +
_asciidoctor-mathematical_
| 0.3.5
| STEM support (must be required using `-r asciidoctor-mathematical`)
| *Asciidoctor Diagram* +
_asciidoctor-diagram_
| 2.2.0
| Diagram blocks (must be required using `-r asciidoctor-diagram`)
| *Asciidoctor Kroki* +
_asciidoctor-kroki_
| 0.8.0
| Diagram blocks (must be required using `-r asciidoctor-kroki`)
| *Rouge* +
_rouge_
| 2.0.0
| Syntax highlighting
| *Pygments (Ruby)* +
_pygments.rb_
| 2.0.0
| Syntax highlighting
| *CodeRay* +
_coderay_
| 1.1.0
| Syntax highlighting
| *Prawn Gmagick* +
_prawn-gmagick_
| 0.0.9
| Accelerates image embedding using GraphicsMagick
| *RGhost* +
_rghost_
| 0.9.7 +
(avoid 0.9.8)
| PDF optimization using Ghostscript (requires `optimize` attribute to be set)
| *Text Hyphen* +
_text-hyphen_
| 1.4.1
| Automatic hyphenation (requires `hyphens` attribute to be set)
| *ICU* +
_ffi-icu_
| 0.5.0
| Locale-aware sorting of index terms
|===
|
