Background Images

Background images can be applied to all content pages using the page-background-image document attribute. A content page is defined as every page in the document except for cover and imported pages. The list of content pages includes the title page as well as non-facing pages in a prepress document.

The page-background-image attribute accepts an inline image macro. The target of the image macro can be an absolute path or a path relative to imagesdir.

You can also assign a page background image per side or per page layout.

When you set page-background-image, the specified image will be applied to the title page as well. You can specify a different image for the title page using the title-page-background-image document attribute.

Alternately, you can turn off the background image on the title page by assigning the value none.

By default, page background images are automatically scaled to fit the bounds of the page (i.e., fit=contain) and centered (i.e., position=center). To alter this behavior, you can set the fit, sizing, and position attributes on the image macro.

Background images, including front and back cover images, can be sized relative to the page using the fit attribute on the image macro. The fit attribute works similarly to the object-fit property in CSS. Its value must be specified as a single keyword, chosen from the table below. The starting size of the image is determined by the explicit width, if specified, or the implicit width. The height is always derived from the width while respecting the implicit aspect ratio of the image. The available space—​the canvas—​for a background image is the page. If the fit attribute is not specified, it defaults to contain. The contain value automatically scales the image to fit the bounds of the page.

If you want to scale the image using one of the sizing attributes (pdfwidth, scaledwidth, width) on the image macro, you must set the fit attribute to the value none (i.e., fit=none).

The fit attribute is often combined with the position attribute, covered next, to control the placement of the image on the canvas.

In addition to scaling, background images for cover pages, content pages, and the title page support positioning using the position attribute on the image macro. The position attribute accepts a syntax similar to the background-position property in CSS, except only the keyword positions are supported. The position consists of two values, the vertical position and the horizontal position (e.g., top center). If only one value is specified (e.g., top), the other value is assumed to be center. If the position attribute is not specified, its value defaults to is center center. The center center value centers the image vertically and horizontally on the page.

The following table lists of the vertical and horizontal positioning keywords the position attribute supports. You can use any combination of these keywords to position the image.

Here’s an example of how to place a background image at the top center of a page:

Here’s how to move it to the bottom right:

If an image dimension matches the height or width of the page, the positioning keyword for that axis has no effect.

If a background image is assigned to the recto pages (right-hand, odd-numbered pages) or verso pages (left-hand, even-numbered pages), the background will be used only for that side.

If a background image isn’t specified for a side, the converter will use the default page background image (page-background-image), if specified. To turn off the background image for a side, assign the value none.

You can configure any background image to be selected per page layout by including the escaped {page-layout} attribute reference in the image path. The reference has to be escaped so it’s not expanded until the converter resolves the image for a given page layout.

The image is resolved the first time a given page layout is used in the document. Using this technique requires that the page layout value be included in the filename of the image (e.g., footer-bg-landscape.png).