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.

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 is specified as a bare image path or as an AsciiDoc inline image macro. Here’s how a background image is specified in the theme file as a bare path:

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

By default, the bare path is resolved relative to the value of the pdf-themesdir attribute. The path can also be an absolute path.

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

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

The target of the inline image macro can be a path relative to the pdf-themesdir attribute (default), an absolute path, or a data URI. If pdf-theme is a path that ends in .yml, and pdf-themesdir is not set, then the images are resolved relative to the directory of the path specified by pdf-theme. If you want to reference an image relative to the document you’re converting, then prefix the target with the {docdir} attribute reference.

title-page:
  background-image: image:{docdir}/images/title-cover.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.