Image Scaling
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.
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.
| Attribute Name | Description |
|---|---|
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 ( |
|
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 ( |
Accepts the same values as |
|
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 |
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. |
Images in running content and page background images also support the fit attribute when specified using the image macro.
See Background Images for details.
|
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 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.
| See this discussion about image quality in PDFs for more information. |
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 Block Image Styles to learn how to set the image-width key in the theme.