To customise PDF exports, you will need the 'Space Administrator' permission which is assigned by a space administrator from the Space Administration screens. See Space Permissions or contact a space administrator for more information.
Confluence's PDF Export feature addresses the most highly voted improvement request for Confluence — more control over PDF exporting. Users can customise their PDF exports using a PDF Stylesheet, which is specific to each space in a Confluence installation. The following aspects of PDF exports can be customised:
Most PDF Stylesheet customisations are handled using Cascading Style Sheets (CSS), while customisations to headers, footers and the title page are handled using a combination of custom HTML and CSS. Hence, you should be familiar with these technologies (or may require some familiarisation with them first), before implementing the customisations you require. |
On this page:
PDF export customisations are specific to each space.
To customise PDF exports, you will need the 'Space Administrator' permission which is assigned by a space administrator from the Space Administration screens. See Space Permissions or contact a space administrator for more information.
There are two areas that control the customisation of space-level PDF exports in Confluence. These are the 'PDF Layout' and 'PDF Stylesheet'.
To access the PDF Layout for customisation,
|
To access the PDF Stylesheet for customisation,
|
Refer to the Basic Customisations section for examples of typical customisations that can be added to your PDF Stylesheet. Once you are familiar with the implementation of basic PDF stylesheet customisations, you may wish to try out some Advanced Customisations. |
|
|
Modifications to page and margin sizes are made in the @page CSS rule.
To make changes to this rule, you would implement the following type of code in the 'PDF Export Stylesheet' of the PDF Stylesheet.
@page
{
/*Page specific styles (that is, customisations of properties) go here*/
}
|
The default page size is based on the locale of your Confluence server. Hence, if this server was located in the US, the default paper size of your PDF export would be US Letter size (8.5 inches wide by 11 inches long). If the server was located in Australia, the default paper size would be A4 (210 mm wide by 297 mm high).
To modify the page size to A4, add a size property to the top of the rule like this:
@page
{
/*The A4 paper size is 210 mm wide by 297 mm high*/
size: 210mm 297mm;
}
|
More information about paper sizes can be found on Wikipedia.
To add a margin of 15 mm to a paper size of A4, your CSS @page rule would look like this:
@page
{
size: 210mm 297mm;
margin: 15mm;
}
|
By default, a table of contents will be generated after the title page, or at the beginning of the document if the 'PDF Space Export Title Page' (of the PDF Layout) is not defined. The look and layout of the table of contents is completely customisable by defining the appropriate CSS rules in the 'PDF Export Stylesheet'.
For details about the CSS rules governing the default styles applied to the table of contents output in PDF exports, download the default CSS rules (from the link above) and examine the specific rules with toc in its name.
To prevent the table of contents being generated in your exported PDF document, add the div.toc rule to the 'PDF Export Stylesheet' section of the PDF Stylesheet and set its display property to none:
div.toc
{
display: none;
}
|
The leader character is used to visually link the name of a heading in the table of contents list with its page number, which is usually aligned to the page's right-hand margin. By default, the leader character is the '.' (dot) character. However, it can be changed by customising the leader character CSS rule span.toclead:before and adding this to the 'PDF Export Stylesheet' section of the PDF Stylesheet.
To change this to a solid line, modify this CSS rule accordingly:
span.toclead:before
{
content: leader(solid);
}
|
To change this it to spaces (that is, blank space), modify this CSS rule to:
span.toclead:before
{
content: leader(space);
}
|
Be aware that using a space as a leader character can make the table of contents list difficult to read.
You can create a title or cover page for an PDF-exported space or subsection using XHTML. Use the 'PDF Space Export Title Page' section of the PDF Layout to do this. The following XHTML code example uses an inline CSS rule to generate a title page.
<div class="fsTitlePage" style="margin-left:auto;margin-top:75mm;margin-right:auto;"> <img src="/download/attachments/12345/titlepage.png"/> </div> |
In the example above, an image called 'titlepage.png' will be centred in the middle of the page. This image is attached to a Confluence page and is referenced via its relative URL (that is, without the Confluence site's base URL component).
You can obtain the URL of an image attached to a Confluence page by viewing the list of attachments on that page and moving your mouse over the attachment's name. The URL of the image should appear in your browser's status bar or you can copy the link. Once you have this link, paste it into the appropriate src="" attribute within your PDF stylesheet and remove the first part of the URL up to the /download/... part.
Headers and footers can be added to a PDF-exported space or subsection also using XHTML. Use the 'PDF Space Export Header' and 'PDF Space Export Footer' sections of the PDF Layout to create a custom header and footer, respectively. For simple headers and footers, plain text is sufficient. The following example added to a header or footer will create a simple copyright notice.
Copyright © 2009, Atlassian Pty Ltd. |
To add page numbering to your documentation, you need to combine some customised XHTML in the header or footer along with some customised CSS in the 'PDF Export Stylesheet'.
First, create a header or footer with an empty span element and give it a unique id, for example pageNum (although this could be anything). This is the page number 'place holder' in your exported PDF document.
<span id="pageNum"/> |
Next, create the following CSS selector rule for this empty span and add it to the 'PDF Export Stylesheet':
#pageNum:before
{
content: counter(page);
}
|
This will add a page number to your header or footer.
Analysing this CSS selector rule in more detail, the |
You can also use the stylesheet to customise the output of just about anything else that will influence the look and feel of the final document. This includes fonts, tables, line spacing, macros, etc. The export engine works directly from the HTML output produced by Confluence. Therefore, the first step in customising something would be to find a selector for the HTML element produced by Confluence or the Confluence macro. Next you would add a CSS rule to the 'PDF Export Stylesheet' and your customisation would appear in the PDF export.
Advanced PDF Stylesheet Customisations