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 sizeThe 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:
Comments (70)
Feb 15, 2007
Jay says:
I am trying to take pdf export of confluence pages. Thus created pdf has au...I am trying to take pdf export of confluence pages. Thus created pdf has autogenerated header (like 'This page last changed.....') and footer (like 'Document generated by Confluence on....' and page no.)
Is it possible to turn this auto generated header/footer without having to going into velocity template changes?
Feb 21, 2007
Kevin Tran says:
Hi Jay, Unfortunately at present, the only way to change the header/footer in P...Hi Jay,
Unfortunately at present, the only way to change the header/footer in PDF exports is to modify the velocity templates. There is an existing request for this feature in JIRA.
http://jira.atlassian.com/browse/CONF-2079
Please add yourself as a watcher so that you can keep up to date. Additionally, you can also vote for the issue's popularity.
Regards,
Kevin
Feb 22, 2007
Olivier Dagenais says:
Hi, I updated and debugged my FO with Apache's FOP but when I piece it back tog...Hi,
I updated and debugged my FO with Apache's FOP but when I piece it back together in the velocity templates, a Confluence PDF export doesn't produce the same results.
A search through the Confluence folder for JAR files yielded this:
confluence/confluence/WEB-INF/lib/fop-0.20.5-atlassian-20060626.jar
...and it appears I was working against version 0.93 of FOP.
Do I interpret this correctly? That Confluence is using an Atlassian-modified version of the previous release of FOP??
Any chance I can upgrade it myself (i.e. is the API still compatible?) or should I log a JIRA case against modernizing the FOP version in Confluence?
Mar 06, 2007
Ivan Benko says:
Hi Olivier, Yes we are indeed using the 0.20.5-atlassian-20060626 in Confluence...Hi Olivier,
Yes we are indeed using the 0.20.5-atlassian-20060626 in Confluence 2.3.3 onwards. Unfortunately, the version you are using 0.93 has a fairly different API and is not compatible with 0.20.5. You should be able to use 0.20 release without change but we already have the latest. In other words, you can't just simply drop the newest jar into the web-inf/lib directory.
FYI - we are in a process of trying to upgrade the FOP package again, as there seems to be some bugs in this version.
Please create a support case in http:/support.atlassian.com if you require further help.
Thanks,
Ivan
Mar 06, 2007
Olivier Dagenais says:
Good to know, thanks! Any ETA on this upgrade? Or perhaps a JIRA issue number ...Good to know, thanks!
Any ETA on this upgrade? Or perhaps a JIRA issue number I can subscribe to??
Thanks, Ivan!
Mar 07, 2007
Ivan Benko says:
Yes Olivier, we do have a related bug opened in JIRA already. Please follow the ...Yes Olivier, we do have a related bug opened in JIRA already. Please follow the progress there.
In particular, the comment from Charles, is specifically aiming on the update of the FOP library.
Let me know if you need additional information.
Thanks,
Ib
Jun 27, 2007
Eric Bardoux says:
Hi, Where is the css file used to render PDF? Because i've modified the site-cs...Hi,
Where is the css file used to render PDF? Because i've modified the site-css.vm to modify the wiki content, but when i export to PDF, i still have the default styles.
Regards
Eric
Jun 27, 2007
Tony Cheah Tong Nyee says:
Hi Eric, I have raised a support ticket for you in our Atlassian Support system...Hi Eric,
I have raised a support ticket for you in our Atlassian Support system. Please follow the update there.
Cheers,
Tony
Jul 21, 2007
hernan g says:
Modify page title for single page export But what about when we use space expor...But what about when we use space export? I modified it to not print the "This page last changed on Jul 02, 2007 by admin." but when I use the space export for the same one page, I get that line again... where is that controlled?
Jul 21, 2007
hernan g says:
ok so I found it (why isn't it documented?) it is in Space.pdfexport.vm in confl...ok so I found it (why isn't it documented?) it is in Space.pdfexport.vm in confluence\spaces
I also changed but not sure who uses it: Page-Hierarchy.pdfexport.vm in confluence\pages (also had the same text)
and after all of this.. I have a bigger problem:
While footer actually do appear in EVERY page like it says here, the common_header_fop.vm only appears on the FIRST page when I exported (space, multiple pages). What kind of a header is that?
Also, I tried using an image in the header, but it is not clear what path to use. if I use relative, then relative to what?
Aug 31, 2007
Anonymous says:
I'd also like to know whether it is possible to use relative paths for images. C...I'd also like to know whether it is possible to use relative paths for images. Can anyone tell us?
Thanks,
Martin
Sep 02, 2007
Fennie Ng says:
Hi Martin, As I know only absolute paths for images are supported at the moment...Hi Martin,
As I know only absolute paths for images are supported at the moment. If you are keen on using relative paths, feel free to raise a request for this issue. Thank you.
Regards,
Fennie
Sep 06, 2007
Anonymous says:
Hi, How could it be possible to have multiple PDF templates for export ? I mea...Hi,
How could it be possible to have multiple PDF templates for export ?
I mean, one global template for space or pages export, and a specific one for some special pages ?
Could it be done by modifying velocity templates ? Or using user defined macros ?
Thanks for your ideas.
Sep 07, 2007
Tony Cheah Tong Nyee says:
Hi there, Unfortunately, this is not supported in Confluence. However, you may ...Hi there,
Unfortunately, this is not supported in Confluence. However, you may be interested to look at the following open feature request regarding having the ability to specify a template to use other than the default instead, when generating a PDF:
Feel free to cast your vote to increase its popularity and add yourself as a watcher for future updates. Additionally, you may also add your comments to the issue to share some idea of yours.
Cheers,
Tony
Oct 19, 2007
Anonymous says:
How to export pages along with the child pages from the pdf export link provided...How to export pages along with the child pages from the pdf export link provided in each page as the admin can do from space admin?
Oct 19, 2007
Imtiaz B Syed says:
How to export pages along with the child pages from the pdf export link provided...How to export pages along with the child pages from the pdf export link provided in each page as the admin can do from space admin?
Oct 22, 2007
Choy Li Tham says:
Hi Imtiaz, In order to export pages along with the child pages to PDF export, y...Hi Imtiaz,
In order to export pages along with the child pages to PDF export, you will need to grant with the "Export Space" permission from the Space administrator. Having that said, you would be able to export the selected pages as well as the child pages within a space unless you have the permission set. For more information regarding PDF export, the following documentation may serve as a reference to you:
Regards,
Choy Li
Oct 28, 2007
Gary Menzel says:
We upgraded to 2.6.0 over the weekend. We had cusomised the PDF footer to ...We upgraded to 2.6.0 over the weekend. We had cusomised the PDF footer to add a version number (easy to add back in again) but we cannot find the neccessary FOP file for this (as documented above). Furthermore, a search does not find this file anywhere. Have we done something wrong - or has something changed dramatically?
Oct 29, 2007
Mei Yan Chan says:
Hi Gary, In Confluence 2.6, these files have been archived in WEB-INF/lib/confl...Hi Gary,
In Confluence 2.6, these files have been archived in WEB-INF/lib/confluence-2.6.0.jar. In order to make modifications to the file you mentioned above, there is a need to extract them and allocate it to the appropriate path. For more information, please see:
Regards,
Mei
Nov 15, 2007
Mike Kadlec says:
Gentlemen, after reading all tech details here I ´ve got an impression that exp...Gentlemen,
after reading all tech details here I ´ve got an impression that expecting nice an dtidy pdf output from Confluence is still sort of "mistery wish".
Anyone have got a THE solution, please ?
Thanks Mike
Nov 15, 2007
Choy Li Tham says:
Hi Mike, after reading all tech details here I ´ve got an impression that expec...Hi Mike,
Could you please elaborate more in details for the above statement so that we can verify from there? Thanks.
Regards,
Choy Li
Nov 19, 2007
Mike Kadlec says:
Hi Choy Li Tham, lets point out just a couple of details here (I wish your resp...Hi Choy Li Tham,
lets point out just a couple of details here (I wish your response is positive!)
Does Confluence support :
Bookmarks by a Header inside a page?
Automatic pictuture/Figure numbering?
Chapters numbering ?
Automatic TOC ?
Automatic list of pictures ?
I understand that with this functionalities we would be looking at another sort of CMSystem.
Best regards,
Mike
Nov 20, 2007
Fennie Ng says:
Hi Mike, Regarding your questions: Bookmarks by a Header inside a page? Conflu...Hi Mike,
Regarding your questions:
Confluence allows user to use URL to make a bookmark. For more information on what Bookmarks can do, feel free to visit Working with Bookmarks. If you think this feature does not meet your requirement, feel free to raise a feature request at our JIRA issue tracker.
This feature is not implemented yet. However, we are aware of this need and it has been tracked here.
If you are referring to Portlet, Script, Hidden and TOC Macros, I am afraid you have to install this plugin manually or via Confluence Plugin Repository.
Confluence allows users to use the Gallery macro (you need to manually edit in 'Wiki Markup' mode to include macros in your page) that creates a gallery of thumbnails from all the images that are attached to a page and displays them in a tabular format.
Regards,
Fennie