The PDF customisation procedures described on this page are only applicable to Confluence 2.10.4 and earlier versions

To customise PDF exports in Confluence 3.0, please use the procedure described in Editing the PDF Stylesheet.

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

The default PDF page size is A4 (210mm x 297mm or 8.27in x 11.7in). Modify the file under your Confluence install directory:

.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_fop.vm

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

<fo:simple-page-master margin-right="2cm" margin-left="2cm" margin-bottom="1cm" margin-top="1cm" page-width="21cm" page-height="29.7cm" master-name="all-pages">

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

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:

<fo:simple-page-master margin-right="2cm" margin-left="2cm" margin-bottom="1cm" margin-top="1cm" page-width="29.7cm" page-height="21cm" master-name="all-pages">

This will generate a PDF export with a Landscape orientation.

Editing 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 Development topics on Atlassian Answers.

List Of PDF-Related Files

.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_header_fop.vm
.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_footer_fop.vm
.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_fop.vm
.../confluence/WEB-INF/classes/com/atlassian/confluence/pages/Page.pdfexport.vm

* 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.

<fo:block text-align="left" font-family="$generalUtil.getDefaultFontFamily()" color="#0050B2">
    This text is printed
</fo:block>

Images

There are two steps involved in adding images to the header and the footer:

  1. 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. 
    <fo:region-before extent="1cm"/>
<fo:region-after extent="1cm"/>
    In the example above, change the "1cm" value to allow yourself as much space as you need for your customization.

  2. 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.

<fo:block>
<fo:external-graphic
width="auto" height="auto"
src="file:///c:/images/operahouse.png" />
</fo:block>

Modify Page Title

This title appears once on the first page of the PDF. An example title is

Demonstration Space : Timesheets
This page last changed on Nov 02, 2006 by Administrator

To modify the page title, go to your Confluence install directory and modify the Velocity macro file

...\confluence\WEB-INF\classes\com\atlassian\confluence\pages\Page.pdfexport.vm

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

...\confluence\WEB-INF\classes\com\atlassian\confluence\spaces\Space.pdfexport.vm

The file contents are shown below

<fo:block text-align="left" font-family="$generalUtil.getDefaultFontFamily()" font-weight="bold" color="#0050B2">
    $generalUtil.escapeXml($page.space.name) : $rendererBean.nativeToAscii($generalUtil.escapeXml($page.title))
    <fo:leader leader-pattern="rule" leader-length="100%"/>
</fo:block>
<fo:block color="grey" font-size="8pt" space-after.optimum="12pt">
    This page last changed on $generalUtil.format($page.lastModificationDate) by
    <fo:inline color="#0050B2">$!page.lastModifierName</fo:inline>.
</fo:block>

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

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

...\confluence\WEB-INF\classes\com\atlassian\confluence\importexport\common_header_fop.vm

Example Header Modification

In between the two FO lines, add

<fo:block text-align="left" font-family="$generalUtil.getDefaultFontFamily()" color="#0050B2">
    Custom Header
</fo:block>

Example Header Modification with Banner

Below is a sample common_header_fop.vm velocity template for header with Banner.

<fo:static-content flow-name="xsl-region-before">

<fo:table width="100%" table-layout="fixed" font-family="serif" font-size="10pt">
		    <fo:table-column column-width="14cm"/>
		    <fo:table-column column-width="3cm"/>
		    <fo:table-body>
			    <fo:table-row>
				    <fo:table-cell color="grey">
					<fo:block text-align="left" font-family="$generalUtil.getDefaultFontFamily()" color="#0050B2">
						<fo:external-graphic width="auto" height="auto" src="file:///c:/images/Top_Banner.jpg"                />
				        </fo:block>
				    </fo:table-cell>
				    <fo:table-cell color="grey">
					    <fo:block text-align="right">
						This is your Customer Header
					    </fo:block>
				    </fo:table-cell>
			    </fo:table-row>
		    </fo:table-body>
	    </fo:table>

</fo:static-content>

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.

  <fo:layout-master-set>
	  <fo:simple-page-master margin-right="2cm" margin-left="2cm" margin-bottom="1cm" margin-top="1cm" page-width="21cm" page-height="29.7cm" master-name="all-pages">
		  <fo:region-body margin-bottom="1.5cm" margin-top="1.5cm"/>
		  <fo:region-before extent="4cm"/>
		  <fo:region-after extent="1cm"/>
	  </fo:simple-page-master>
  </fo:layout-master-set>

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

Page footers appear on the bottom of every page. An example footer is

Document generated by Confluence on Dec 11, 2006 09:35                    Page1

To modify the footer, go to your Confluence install directory and modify the Velocity macro file

...\confluence\WEB-INF\classes\com\atlassian\confluence\importexport\common_footer_fop.vm

Example Footer Modification

To produce this footer

Created on Dec 11, 2006 11:43
Copyright Altassian Software

Locate this line in common_footer_fop.vm

<fo:block>Document generated by Confluence on $generalUtil.formatDateTime($exportDate)</fo:block>

Replace it with the following Velocity code

<fo:block>Created on $generalUtil.formatDateTime($exportDate)</fo:block>
<fo:block>Copyright Altassian Software</fo:block>

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

 <fo:static-content flow-name="xsl-region-after">
	<fo:block>
		<fo:leader leader-pattern="rule" leader-length="100%"/>
	</fo:block>
	<fo:table width="100%" table-layout="fixed" font-family="serif" font-size="10pt">
		    <fo:table-column column-width="14cm"/>
		    <fo:table-column column-width="3cm"/>
		    <fo:table-body>
			    <fo:table-row>
				    <fo:table-cell color="grey">
					    <fo:block>Document generated by Confluence on $dateFormatter.formatDateTime($exportDate)</fo:block>
						<fo:block>Created on $generalUtil.formatDateTime($exportDate)</fo:block>
						<fo:block>Copyright Altassian Software</fo:block>
				    </fo:table-cell>
				    <fo:table-cell color="grey">
					    <fo:block text-align="end">Page <fo:page-number/></fo:block>
				    </fo:table-cell>
			    </fo:table-row>
		    </fo:table-body>
    </fo:table>
</fo:static-content>

Sample PDF Footer Image:

Exporter Velocity Context Additions

In addition to the objects available to all exporters, the PDF exporter has access to the following additional objects:

(When exporting entire spaces)

Velocity Reference

Description

Javadoc Reference

$space

The Space object for the space being exported.

Space

$contentTree

A ContentTree object representing the hierarchy of pages in the space to be exported.

ContentTree

(When exporting single pages)

Velocity Reference

Description

Javadoc Reference

$page

The Page object for the page being exported.

Page

Export PDF in another Language

Create PDF in another language

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.