You can add background images to every page in your document with the
page-background-image document attribute.
A background image can also be assigned to recto or verso pages using
A background image for the title page can also be specified using the
Alternatively, you can define background images in your theme.
Background images can be assigned to every page in a document using the
page-background-image document attribute.
The attribute accepts an inline image macro.
The target of the image macro can be a path relative to imagesdir or an absolute path.
= Document Title :page-background-image: image:bg.png
By default, page background images are automatically scaled to fit the bounds of the page (i.e.,
fit=contain) and centered (i.e.,
You can set the fit, sizing, and position attributes on the image macro.
The size of the background image can be controlled using any of the sizing attributes on the image macro when
= Document Title :page-background-image: image:bg.png[fit=none,pdfwidth=25%] (1)
Background images, including front and back cover images, can be sized relative to the page using the
fit attribute on the image macro.
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.
fit attribute is not specified, it defaults to
contain value automatically scales the image to fit the bounds of the page.
The image is scaled up or down while retaining its aspect ratio to fit within the available space. (default)
The image is scaled up or down while retaining its aspect ratio so the image completely covers the available space, even if it means the image must be clipped in one direction.
The image is scaled down while retaining its aspect ratio to fit within the available space. If the image already fits, it is not scaled.
The image is scaled to fit the available space even if it requires modifying the aspect ratio of the image.
The image is not scaled.
If you need to scale the image using one of the sizing attributes (
width), you must set the
fit attribute for
= Document Title :page-background-image: image:mark.jpg[fit=none,pdfwidth=50%]
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 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.,
If only one value is specified (e.g.,
top), the other value is assumed to be
position attribute is not specified, its value defaults to is
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.
|Vertical Positions||Horizontal Positions|
Here’s an example of how to place a background image at the top center of a page:
= Document Title :page-background-image: image:bg.png[position=top]
Here’s how to move it to the bottom right:
= Document Title :page-background-image: image:bg.png[fit=none,pdfwidth=50%,position=bottom right]
If an image dimension matches the height or width of the page, the positioning keyword for that axis has no effect.
Recto and verso background images
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.
= Document Title :page-background-image-recto: image:bg.png[fit=none,pdfwidth=20%,position=bottom right] :page-background-image-verso: image:bg.png[fit=none,pdfwidth=20%,position=bottom left]
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 disable the background image for a side, use the value