1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
= 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), 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.
[#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 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:
[,yaml]
----
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:
[,yaml]
----
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}` or `\{docimagesdir}` attribute references, which both resolve to an absolute path.
[,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.
|
