Editing the PDF Stylesheet

Confluence administrators and space administrators can customise the PDF exports for individual spaces. Possible customisations include:

A title page, which can include images
Page headers and footers, each with customisable content such as page numbering
Table of contents with page numbering
Page and margin sizes

On this page:

Before You Start

Please take note of the following points:

Most PDF customisations use a combination of HTML and CSS (Cascading Style Sheets). You need to be comfortable with these technologies before applying any customisations.
PDF customisations are unique to each space.
There two areas that control Confluence custom PDF exports. You will need to visit each of these areas to ensure your PDF exports are customised to your requirements:
- The PDF Layout defines the title page, headers and footers.
- The PDF Stylesheet defines the page size and margins, font, colour, list numbering, and all other style customisations.

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:

Go to the 'Space Admin' tab of the Browse Space view. To do this:
- Go to a page in the space, open the 'Browse' menu and select 'Space Admin'.
  'Space Admin' is displayed only if you are a space administrator for that space or you are a Confluence system administrator.
Click 'PDF Layout' in the 'Look and Feel' section of the left-hand panel.
Click the 'Edit' button. You can now customise the HTML that generates 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.
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.
Click 'Save'.

Customising the PDF Stylesheet

You can adjust the appearance of the PDF pages by editing the CSS stylesheet.

To customise the PDF Stylesheet:

Go to the 'Space Admin' tab of the Browse Space view. To do this:
- Go to a page in the space, open the 'Browse' menu and select 'Space Admin'.
  'Space Admin' is displayed only if you are a space administrator for that space or you are a Confluence system administrator.
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.
Click the 'Edit' button.
Enter your customisations into the text box as required. The PDF stylesheet section accepts Cascading Style Sheets (CSS) rules.
Click 'Save'.

Default CSS Settings

If no PDF customisations are defined on 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 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.
You can also make further CSS customisations as required. This means you can override any default CSS rule by redefining it in the 'PDF Export Stylesheet' section with your own customisations.

PDF Export Methods

There are two PDF export methods (see Exporting Confluence Pages and Spaces to PDF):

Exporting a single page via the 'Tools' menu on the page or blog post. Only the PDF stylesheet customisations apply to single page exports.
Exporting one or more pages via the space export function. When exporting a space, all your customisations apply, including both the PDF stylesheet and the PDF layout.

To make your PDF layout customisations apply to a single page exported to PDF, either:

use the 'space export' method to export that single page only, or
if your header and footer customisations contain only text, follow the appropriate customisations provided in the advanced PDF stylesheet customisations.

Examples of Basic Customisations

This section provides examples of typical customisations that you can add to your PDF stylesheet. Once you are familiar these basic customisations, you may wish to try some advanced customisations.

Page Customisations

Modifications to page and margin sizes are made in the @page CSS rule. To make changes to this rule, implement the following type of code in the PDF stylesheet.

@page
{
/*Page specific styles (that is, customisations of properties) go here*/
}

Customising the 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 size (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 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.

Customising the Page Margins

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;
}

Customising the Table of Contents

By default, a table of contents will be generated after the title page, or at the beginning of the document if no title page is defined in the PDF layout. To make changes to the look and layout of the table of contents, define the appropriate CSS rules in the PDF stylesheet.

For details about the default CSS rules applied to the table of contents, download the default CSS rules (from the link above) and examine the specific rules with toc in their name.

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 the name of a heading in the table of contents with its page number. The page number is usually aligned to the right-hand margin of the page. By default, the leader character is the '.' (dot) character. You can change it by customising the leader character CSS rule span.toclead:before and adding this to the PDF stylesheet.

To change the leader character to a solid line, modify the CSS rule to:

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

To change the leader character to spaces, modify the 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 difficult to read.)

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;  
}

Adding a Title Page

You can create a title or cover page to your PDF document using HTML. Use the 'PDF Space Export Title Page' section of the PDF layout to do this.

Adding a New Title Page

The following example uses HTML with an inline CSS rule to generate a title page.

<div class="fsTitlePage" style="margin-left:auto;margin-top:75mm;margin-right:auto;page-break-after:always">
<img src="/download/attachments/12345/titlepage.png"/>
</div>

Including Content Above Table of Contents in Default Title Page

The following example includes content above the automatically-generated table of contents that appears on the default title page, so that your title page includes your own content plus the table of contents.

<div class="fsTitlePage" style="margin-left:auto;margin-top:75mm;margin-right:auto;">
<img src="/download/attachments/12345/titlepage.png"/>
</div>

Adding an Image to your Title Page

In the examples above, the title page includes an image called 'titlepage.png', centred in the middle of the page. The image is attached to a Confluence page and is referenced via its relative URL (that is, we use only the last part of the URL, excluding the Confluence site's base URL).

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

Attach the image to a Confluence page.
View the list of attachments on that page.
Right-click the image and copy its location.
Paste the link into the appropriate src="" attribute within your PDF stylesheet, as shown above.
Remove the first part of the URL before /download/....

Adding Headers and Footers

You can add headers and footers to your PDF pages using HTML. Use the 'PDF Space Export Header' and 'PDF Space Export Footer' sections of the PDF layout to do this. For simple headers and footers, plain text is enough. The following example adds a simple copyright notice.

Copyright © 2010, Atlassian Pty Ltd.

Adding Page Numbering to a Header or Footer

To add page numbering to your documentation, you need to combine some customised HTML in the header or footer with some customised CSS in the PDF stylesheet.

Create a header or footer with an empty span element and give it a unique ID, for example pageNum. This is a place holder for the page number in your PDF document.
```
<span id="pageNum"/>
```
Create the following CSS selector rule for the empty span and add it to the 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 before the span tag.

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.

Child pages