Asciidoctor PDF: watermark on all pages but the title page

Asciidoc is a nice markup language for documentations and reports. When writing reports, one common need is to add a watermark on pages. However, sometimes, it is better to not add it on the title page.

To add a watermark, the simplest today is to add a background image - opposed to HTML rendering where some CSS can solve it without any asciidoc(tor) configuration.

Since we render in PDF the document, we know the page size and can do a high quality image for the watermark. Assuming it is called watermark.png and it is in images folder, we can add our watermark this way:

= My Asciidoctor PDF Report
:page-background-image: image:images/watermark.png[]
v1.0.0
Romain Manni-Bucau

Rest of the document....

The page-background-image attribute enables to add an image inline macro as background of all pages. You can even mix it with some image macro attributes to reduce the opacity of the watermark:

= My Asciidoctor PDF Report
:page-background-image: image:images/watermark.png[opacity=50%]

...

However this will add the watermark on all pages, including the title one which can completely breaks your title if you use an image already. The solution is to ask Asciidoctor PDF to not add any background image on the title page using the specific title page attribute title-page-background-image: 

= My Asciidoctor PDF Report
:title-page-background-image: none
:page-background-image: image:images/watermark.png[opacity=50%]

...

With this configuration, you ask the title page to not have a specific background image - so you can use a background color if you want, and all other pages to use your watermark with some transparency to keep the text readable.

Indeed you can also specify a title page backrgound image which would replace the watermark one for that specific page.

With that small trick we reach our goal to have a clean title page and watermarks on all other pages which is pretty convenient to share an INTERNAL, DRAFT, CONFIDENTIAL, .... document :).

Last tip will be that, thanks to asciidoctor-pdf theming, you can also make that configuration part of a theme instead of the document attributes or you can externalize them, passing attributes at rendering time - through the command line or plugin configuration if you use Maven or Gradle plugins. This enables to easily drop the watermark without modifying the document once it is in final version or even render the same document with conditional rendering blocks very easily.