Confluence pages can be output to PDF and some resulting PDF content can be modified. While page content itself is not open to customisation without major source-code modifications, this guide covers the easier task of modifying the plain text contained in page titles, headers and footers and page size.
 | Change in Confluence 2.6.0
The Velocity template files (files whose names end in .vm) were moved inside the main confluence-<version>.jar file with the release of Confluence 2.6.0 (i.e. $CONFLUENCE_INSTALL/confluence/WEB-INF/lib/confluence-2.6.jar in version 2.6). If you are unfamiliar with editing the contents of a .jar file, you may find these instructions useful.
Alternatively Java Servlet Technology allows you to use an unpacked version of the desired file in the WEB_INF/classes directory. Make sure you reproduce the exact directory (package) structure. |
Change PDF page size
How to Change the page size
The default PDF page size is A4 (210mm x 297mm or 8.27in x 11.7in). Modify the file under your Confluence install directory:
To change the page size for PDF export, page-width and page-height parameters have to be edited in the above mentioned file. Locate the line
and change the values for page-width and page-height as required.
This file is pretty self-explanatory. Change to the following values:
- page-width="21.59cm"
- page-height="27.94cm"
Optionally you can modify the margins. To give the page a half-inch margin all around:
- margin-right="1.27cm"
- margin-left="1.27cm"
- margin-bottom="1.27cm"
- margin-top="1.27cm"
Landscape orientation
To change the default A4 +Portrait+ size to +Landscape+ follow the instructions below:
By default the page orientation for PDF export is set to "Portrait" with page-width="21cm" and page-height="29.7cm". To change the orientation to Landscape, swap the page-width and page-height measurement values as shown below:
This will generate a PDF export with a Landscape orientation.
Editing PDF content
How to edit PDF content:
Confluence uses Apache FOP to write Confluence content to XSL-FO format, and uses Velocity macro files to render PDF headers, footers and page titles. For information on more content editing, study the XSL-FO examples.
Always stop Confluence before editing a Velocity macro file. Users who are stuck can obtain technical assistance by posting the modified Velocity file to the Confluence Developer Forum.
List Of PDF-Related Files
- The above example is for Unix-based systems, so Windows users should use back-slashes instead forward-slashes
- An example Windows install directory is C:\confluence-2.2.9-std
- An example Linux install directory is /opt/confluence-2.2.9/
Text
Inserting the example XSL-FO tag below into the relevant Velocity macro file will output a new line with This text is printed in plain text.
Images
There are two steps involved in adding images to the header and the footer:
- You need to modify common_fop.vm and adjust the margins, and sizes of the two regions (region-before and region-after) to fit in the image.
In the example above, change the "1cm" value to allow yourself as much space as you need for your customization.
- Insert the example XSL-FO tag below into the relevant Velocity macro file to embed the local image c:\images\operahouse.png into the PDF.
You will need to convert the file location into a "file URI" before adding it the macro file.
For Windows systems, the method is to replace all back-slashes in the local path with forward-slashes and prefix the result with file:///
For UNIX-based systems prefix the path with file:// eg /tmp/image.png becomes file:///tmp/image.png
There is a good explanation for this format in Windows here and if you're really keen (or having problems) a fuller description is here.
Modify Page Title
Modify page title for single page export
This title appears once on the first page of the PDF. An example title is
To modify the page title, go to your Confluence install directory and modify the Velocity macro file
If you want the modification of the page title to take into effect for space export, go to your Confluence install directory and modify the Velocity macro file
The file contents are shown below
Explanation of the Velocity code from the above example
| Velocity Code |
Prints |
| $generalUtil.escapeXml($page.space.name) |
Space Name |
| $rendererBean.nativeToAscii($generalUtil.escapeXml($page.title)) |
Page Name |
Modify Page Headers for Space Export
How to modify page headers
By default, no page header is printed with PDF exports. To add one, go to your Confluence install directory and modify the Velocity macro file
Example Header Modification
In between the two FO lines, add
Example Header Modification with Banner
Below is a sample common_header_fop.vm velocity template for header with Banner.
 |
If you can't see your banner or image, update the value of <fo:region-before extent="1cm"/> in the common_fop.vm template to 4 or 5 cm according to the size of your banner or image. Please see CONF-9082 for a feature request on increasing the default value. |
A Sample of Custom PDF Header with A Banner on the top
A Sample of Custom PDF Header with A Logo on the Right Top
Modify Page Footers for Space Export
How to modify page footer
Page footers appear on the bottom of every page. An example footer is
To modify the footer, go to your Confluence install directory and modify the Velocity macro file
Example Footer Modification
To produce this footer
Locate this line in common_footer_fop.vm
Replace it with the following Velocity code
To produce a footer with a ruler on top and page number on right and some copy right content on bottom then you can use the sample common_footer_fop.vm template below
Sample PDF Footer Image:
