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

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). If a unit of measurement is not specified (or not recognized), points (pt) is assumed. Intended to be used for the PDF converter only.

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 key from theme

Accepts the same values as pdfwidth. Only applies to block images and 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.

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

  • vw (percentage of page width)

  • % (percentage of content area width)

In all cases, the width is converted to pt.

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.

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.