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%), 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 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.

fit

(Inline image only) If the value is line, the image will be scaled down proportionally, as necessary, to fit the height of a line of text. If the value is none, the image will never be scaled down to fit within the height of the content area. The none value should only be used as a workaround in cases when the converter is scaling the image when it shouldn’t.

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. However, the acceptable values of the fit attribute in those cases differs from the acceptable values for an inline image. See Background Images for details.

Default sizing

An image is always sized based on the user-specified or intrinsic width (aka the resolved width), then its height is scaled proportionally. The computed height of the image is honored unless this value exceeds the height of the content area. In this case, the image is scaled down to fit within the content area.

The height of the content area is typically the space between the top and bottom margins of the page. However, the content area in table cells is handled in two phases.

Inline image sizing in table cells

In tables, each cell is considered its own content area. That content area is computed based on how much space the content requires, though still limited to the space between the top and bottom margins of the page. Inline images in table cells are permitted to increase the height of the cell. However, there can be differences in how the image is sized in a normal cell compared to an AsciiDoc table cell.

The calculation of the content’s height in a normal table cell can be inaccurate, often impacted by the font used. When the table cell is rendered, its height is restricted to the computed height. This can impact the sizing of inline images in a normal table cell if fit=line is set on the image. If the computed height ends up being less than the line height, the image will be scaled down to fit. If you want to prevent the converter from attempting to scale down the height of the inline image in a normal table cell, don’t use fit=line or set fit=none on the inline image.

The content area of an AsciiDoc table cell is computed more accurately. Thus, when you specify the a style on a table cell, the scaling of an inline image is true. An inline image will never be scaled down if it fits within the maximum available height of a single page. In this scenario, the fit=line attribute will work in the same way it does outside a table cell.

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.

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.