Customising Exports to PDF

Customising the PDF Layout

You can add your own HTML to customise the title page, page headers and page footers in the PDF output.

To customise the PDF Layout:

1. Choose Browse > Space Admin.
   Space Admin is displayed only if you are a space administrator for that space or you are a Confluence system administrator.

2. Click PDF Layout in the 'Look and Feel' section of the left-hand panel.
3. Click Edit, and customise the HTML that generates the following areas in the exported PDF document:
   
   • PDF Space Export Title Page – title page.
   • PDF Space Export Header – page headers.
   • PDF Space Export Footer – page footers.
4. Enter your customisations into each text box as required. The PDF layout section accepts HTML code. You can include inline CSS in the HTML too. Save your work.

Customising the PDF Stylesheet

You can adjust the appearance of the PDF pages by making CSS customisations in the PDF Stylesheet screen as required.

• To get started, you can download the default CSS rules of the PDF stylesheet: confluencedefaultpdf.css. Any rule defined in this file can be customised and added to the 'PDF Export Stylesheet' section.
• Your customisations override any default CSS rule.
• If no PDF customisations are defined in the PDF Stylesheet screen, the default CSS rules will be applied to your PDF exports. By default, the export does not include a title page, headers or footers.

To customise the PDF Stylesheet:

1. Choose Browse > Space Admin.
   Space Admin is displayed only if you are a space administrator for that space or you are a Confluence system administrator.

2. Click PDF Stylesheet in the left-hand panel. The 'PDF Export Stylesheet' section appears, showing the current contents of your PDF stylesheet. It contains all CSS rule customisations applied to the pages in the space.
3. Click Edit and enter your customisations into the text box as required. The PDF stylesheet section accepts Cascading Style Sheets (CSS) rules. Save your work.

Example Customisations

This section provides examples of typical customisations that you can add. See also Advanced PDF Customisations.

Page Size

The default page size is based on the locale of your Confluence server. For example, if this server is located in the US then the default paper size of your PDF export will be US Letter (8.5 inches wide by 11 inches long). If the server is located in Australia, the default paper size will be A4 (210 mm wide by 297 mm long). More information about paper sizes can be found on Wikipedia.

To modify the page size to A4, edit the PDF Stylesheet to add a size property to the CSS@page rule, like this:

@page
{
/*The A4 paper size is 210 mm wide by 297 mm long*/
size: 210mm 297mm;
}

Page Orientation: Landscape or Portrait

To change the page orientation of your PDF document, simply reverse the order of the values declared in the @page rule's size property. The first and second values of this property represent the width and height of the page, respectively.

For example, to generate PDF space exports in A4-sized landscape orientation, your @page rule might look like this:

@page
{
/*A4-sized pages in landscape orientation are 297 mm wide by 210 mm long*/
size: 297mm 210mm;
}

Page Margins

To set all margins to 15 mm, with a paper size of A4, edit the CSS @page rule in the PDF Stylesheet, like this:

@page
{
size: 210mm 297mm;
margin: 15mm;
}

To set the margins independently, edit the @page rule as follows:

@page
{
margin-top: 2.54cm;
margin-bottom: 2.54cm;
margin-left: 1.27cm;
margin-right: 1.27cm;
}

To set margins to provide a gutter for binding a printed document, use the :left and :right pseudo-classes, as follows:

@page :left 
{ 
margin-left: 4cm; 
margin-right: 3cm; 
} 
@page :right 
{ 
margin-left: 3cm; 
margin-right: 4cm; 
}
@page :first 
{ 
margin-top: 10cm /* Top margin on first page 10cm */ 
}

Note the use of the :first pseudo-class in the example above to define distinct margins for a cover or title page.

Page Breaks

By default, Confluence pages are exported without page breaks, so that shorter pages will appear on the same PDF page.

To make each Confluence page appear on a separate page in the PDF file, add the following rule in the PDF Stylesheet:

.pagetitle
{
page-break-before: always;
}

Title Page

You can add a title page to your PDF document by adding HTML to the Title Page section of the PDF Layout screen. The following example creates the title page and adds a title:

<div class="fsTitlePage">
 <img src="/download/attachments/590719/titlepage.png" />
<div class="fsTitle">Planning for Confluence 4.0</div>
</div>

Use CSS rules in the PDF Stylesheet to control the appearance of the title page and the title text:

.fsTitlePage 
{
margin-left: auto;
margin-top: 50mm;
margin-right: auto;
page-break-after:always 
} 

.fsTitle
{
font-size: 42px;
font-weight: bold;
margin: 72px 0 4px 0;
text-align:center;
}  

Adding an Image to the Title Page

In the example above, the title page includes an image called 'titlepage.png', centred in the middle of the page. The "590719" in the src attribute is the ID number of the page to which the image is attached.

Follow these instructions to include an image on your title page:

1. Attach the image to a Confluence page.
2. View the list of attachments on that page, then right-click the image and copy its location.
3. Paste the link into the appropriate src="" attribute in your PDF Stylesheet, as shown above.
4. Edit the image URL so that it is relative, by removing the first part of the URL before /download/....

Table of Contents

By default, a table of contents will be generated after the title page, or at the beginning of the PDF document if no title page is defined in the PDF Layout. To see the default CSS rules applied to the table of contents, download the default CSS rules (confluencedefaultpdf.css) and examine the specific rules with toc in their name.

To make changes to the appearance of the table of contents, define CSS rules in the PDF Stylesheet.

Disabling the Table of Contents

To prevent the table of contents from being generated in your PDF document, add the div.toc rule to the PDF Stylesheet and set its display property to none:

div.toc
{
display: none;
}

Changing the Leader Character in the Table of Contents

The leader character is used to link a heading in the table of contents with its page number. By default, the leader character is the '.' (dot) character. Leader values of dotted, solid and space are allowed. You can also use a string, for example leader(". . . ").

To change the leader character to a solid line, modify the leader() value on the content property of the CSS rule as follows:

span.toclead:before
{
content: leader(solid);
}

Headers and Footers

You can add headers and footers to your PDF pages using the 'Header' and 'Footer' sections of the PDF Layout screen. By default, headers and footers only apply to a space export and not to exports of single pages (however, see Advanced PDF Export Customisations). The following example adds a simple copyright notice.

Copyright © 2011, Atlassian Pty Ltd.

Page Numbering

To add page numbering, you need to combine customised HTML in the PDF Layout with customised CSS in the PDF Stylesheet.

1. PDF Layout HTML: In the Footer section (or the Header section), use an empty span element with a unique ID, for example pageNum, to act as a place holder for the page number.

   HTML - PDF Layout: Footer Section

   <span id="pageNum"/>
   

2. PDF Stylesheet CSS: Create the following CSS selector rule for the empty span:

   CSS - PDF Stylesheet

   #pageNum:before
   {
   content: counter(page);
   }
   

Analysing the above CSS selector rule in more detail:

• The #pageNum rule selects the HTML element with the specified ID of "pageNum", which is the span element we created for the header or footer.
• The :before part of the selector is a pseudo class that allows the insertion of content before the span element is processed.
• The counter(page) is a function that returns the current page number as its content.
• The content property tells the CSS processor that dynamic content (that is, an incrementing page number) is to be inserted at the span tag.

Wrapping Long Words

In order to break long words or words that are not separated by whitespace, add a selector to the PDF stylesheet containing the word-wrap property with a value of break-word:

div 
{  
word-wrap: break-word;  
}

General Formatting

You can 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 is to find a selector for the HTML element produced by Confluence or the Confluence macro. Then add a CSS rule to the PDF stylesheet. Your customisation will appear in the PDF export.

Notes

• Demotion of heading elements: h1, h2, and so on. Due to the hierarchical manner in which a space is exported, Confluence will modify the heading elements to generate a uniform appearance for the entire space export. This means that headings will be demoted. This will affect the application of custom PDF Stylesheets. It is possible to calculate the amount by which a heading will be demoted in order to have the correct CSS styling applied. A heading will be demoted by the value of its depth in the export tree. A page at the first level will be demoted by 1 (all <h1> elements will become <h2> elements, and so on). A page at the second level will be demoted by 2, and so on.

• Atlassian support for PDF customisation is limited. We support the mechanism for customising the PDF layout with HTML and CSS, and we will help if the mechanism is broken or does not work as we say it should in our published examples. But, since custom HTML and CSS offer potentially limitless possibilities, Atlassian will not support issues that are caused by or related to PDF customisations.

Related Topics

Advanced PDF Export Customisations