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
|
= Image Scaling
:description: An image can be scaled using one of the width attributes, such as pdfwidth, scaledwidth, image-width, or width.
PDF is a fixed-width canvas, therefore you almost always need to specify a width to get the image to fit properly on the page.
[#width-attributes]
== Image width attributes
There are several attributes available for specifying the width of an image.
These attributes are listed in the following table in order of precedence.
[cols="1s,3"]
|===
|Attribute{nbsp}Name | Description
|<<pdfwidth,pdfwidth>>
|The display width of the image as an absolute size (e.g., 2in), percentage of the content area width (e.g., 75%), percentage of the intrinsic width of the image (e.g., 50iw), or percentage of the page width (e.g., 100vw).
If a unit of measurement is not specified (or not recognized), points (`pt`) is assumed.
_Intended to be used for the PDF converter only._
|scale
|A percentage of the intrinsic width of the image.
|scaledwidth
|The display width of the image as an absolute size (e.g., 2in) or percentage of the content area width (e.g., 75%).
If a unit of measurement is not specified, percentage (`%`) is assumed.
If a unit of measurement is recognized, points (`pt`) is assumed.
_Intended to be used for print output such as PDF._
|<<image-width,image-width key from theme>>
|Accepts the same values as `pdfwidth`.
_Only applies to block images and xref:theme:block-images.adoc#fallback[is set in the theme], not the content._
|width
|The unitless display width of the image (assumed to be pixels), typically matching the intrinsic width of the image.
If the value ends in `%` (not recommended), it's assumed to be the percentage of the available content area width.
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, assuming canvas is 96 dpi) unless the width exceeds the content area width, in which case the image is scaled down to the content area width.
|===
TIP: Images in running content and page background images also support the `fit` attribute when specified using the image macro.
See xref:background-images.adoc[] for details.
[#default]
== Default sizing
An image is always sized according to the explicit or intrinsic width, then its height is scaled proportionally.
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.
[#pdfwidth]
== 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
* pc
* iw (percentage of intrinsic width of image)
* vw (percentage of page width)
* % (percentage of content area width)
In all cases, the width is converted to pt internally.
NOTE: See this https://groups.google.com/forum/#!msg/prawn-ruby/MbMsCx862iY/6ImCsvLGfVcJ[discussion about image quality in PDFs^] for more information.
[#image-width]
== Fallback width for block images
To scale all block images that don't define either a `pdfwidth` or `scaledwidth` attribute on an image macro in your document, assign a value to the `image-width` key in your theme file.
If specified, the `image-width` value takes precedence over the `width` attribute on an image macro.
See xref:theme:block-images.adoc[] to learn how to set the `image-width` key in the theme.
== Align block image to page boundaries
If you want a block image to align to the boundaries of the page (not the content margin), specify the `align-to-page` option (e.g., `opts="align-to-page"`).
This is most useful when using vw units because you can make the image cover the entire width of the page.
|
