= Theme Images
:description: Some category keys allow background, foreground, logo, and category-specific images to be specified directly in the theme.

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

[#formats]
== 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: CAUTION: The GIF (.gif), WebP (.webp), TIFF (.tiff), BMP (.bmp), and interlaced PNG formats are not supported unless you install prawn-gmagick.
See xref:ROOT:image-paths-and-formats.adoc#other-image-formats[Supporting additional image file formats] for details.

[#paths]
== 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]
== 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.
xref:covers.adoc[Front and back cover images] are handled like background images, too.

[#specify]
=== 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:

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

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

[,yaml]
----
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:

[,yaml]
----
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.

[,yaml]
----
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).

[#attributes]
=== 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.

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

See xref:ROOT:background-images.adoc[] for the available `fit` and `position` values.
See xref:ROOT:image-scaling.adoc[] to learn about the sizing attributes the image macro accepts.

[#recto-and-verso]
=== 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`.

[,yaml]
----
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.

[,yaml]
----
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`.

[,yaml]
----
title-page:
  background-image: none
----

[#foreground]
== 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`.

[,yaml]
----
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.
