Theme Images

Some category keys allow background, foreground, and other category-specific images to be specified directly in the theme.

Supported image formats

The theme supports the following image formats:

PNG (.png)
JPEG (.jpg)
SVG (.svg)

When specified, the filename of the image must use the file extension that matches its format.

CAUTION: The GIF (.gif), TIFF (.tiff), BMP (.bmp), and interlaced PNG formats are not supported unless you install prawn-gmagick. See Supporting additional image file formats for details.

Image paths in the theme

In the theme, an image can be specified as an AsciiDoc inline image macro. The image can also be specified as a bare path, except in running content. The benefit of using the image macro is that you can specify configuration, such as the alt text and size.

The image path can be an absolute path, a data URI, or a relative path. If the image path is absolute or a data URI, the path is used as is. If the image path is relative, it’s resolved relative to the value of the pdf-themesdir attribute. If the value of the pdf-theme attribute is a path that ends in .yml, and pdf-themesdir is not otherwise set, then images are resolved relative to the directory of the theme path.

If you want to reference an image relative to the document you’re converting, prefix the path with the {docdir} or {docimagesdir} attribute references, which both resolve to an absolute path. The docimagesdir is a combination of the docdir and imagesdir attribute values. When using one of these attribute references, it should be followed by the path separator.

Background images

Several key categories, such as page, title-page, and the running content header and footer, allow a background image to be specified directly by the theme with the background-image key. Front and back cover images are handled like background images, too.

Specify a background image in the theme

In the theme, a background image can specified either using the AsciiDoc inline image macro or as a bare image path. Here’s how a background image is specified in the theme file as a bare path:

title-page:
  background-image: title-cover.png

Here’s how the background image is specified using the inline image macro:

title-page:
  background-image: image:title-cover.png[]

As described above, these relative paths will be resolved from the pdf-themesdir. Here’s an example of an image that is resolved relative to the imagesdir value of the document being converted:

title-page:
  background-image: image:{docimagesdir}/title-cover.png[]

Per page layout

You can configure any background image to be selected per page layout by including the {page-layout} attribute reference in the image path.

footer:
  background-image: image:footer-bg-{page-layout}.png[]

The image is resolved once per page layout that’s encountered in the document. Using this technique requires that the page layout value be included in the path of the image (e.g., footer-bg-landscape.png).

Fit, width, and position

By default, background images are automatically scaled to fit the bounds of the page (i.e., fit=contain) and centered (i.e., position=center). Wrapping the value in the image macro allows you to customize an image’s size and position. The size of the image assigned with an image macro can be controlled using the sizing attributes, fit, pdfwidth, scaledwidth, or width, when fit=none. The position of the image can be controlled using the position attribute.

page:
  background-image: image:page-bg.png[fit=none,position=top center]

See Background Images for the available fit and position values. See Image Scaling to learn about the sizing attributes the image macro accepts.

Recto and verso

The page category allows a background image to be set for recto pages (right-hand, odd-numbered pages) and verso pages (left-hand, even-numbered pages). The recto background image is specified using page-background-image-recto and the verso background image using page-background-image-verso.

page:
  background-image:
    recto: image:page-bg-recto.png[]
    verso: image:page-bg-verso.png[]

If you define the keys using the flattened structure (e.g., page-background-image-recto), you can also set the default page background image (page-background-image), which will be used as a fallback if a background image isn’t specified for a given side.

page-background-image: image:page-bg.png[]
page-background-image-verso: image:verso-bg.png[]

Deactivate a background image

To deactivate an inherited background image, assign the value none to background-image.

title-page:
  background-image: none

Foreground images

In addition to the background-image key, the page category has a foreground-image key. The page-foreground-image key accepts the same types of values and image macro attributes as background-image.

page:
  foreground-image: image:watermark.svg[]

By default, a foreground image is automatically scaled to fit the bounds of the page (i.e., fit=contain) and centered (i.e., position=center). A foreground image can’t be assigned only to recto pages or verso pages.