Customise Exports to PDF
Confluence administrators and space administrators can customise the PDF exports for individual spaces.
Please note:
- PDF customisations are unique to each space.
- PDF customisation only applies to space exports (not single page exports via Tools > Export to PDF)
- Confluence's PDF customisations use a combination of HTML and CSS (Cascading Style Sheets).
- To achieve a particular requirement in the exported PDF file, you make changes in one or both of the following:
- The PDF Layout, where HTML is used to define the structure of the exported content, including features such as the title page, headers and footers.
- The PDF Stylesheet, where CSS is used to define the style of elements in the exported content, such as page size and margins, font, colour, and list numbering.
For further customisations, see the Advanced PDF Export Customisations page.
Customising the PDF Layout
You can add your own HTML to customise the title page, page headers and page footers in the PDF output.
Setting a global PDF layout
- Choose the cog icon
, then choose General Configuration under Confluence Administration - Choose PDF Layout. You can enter HTML and CSS that will be rendered on the PDF title page, as well as page headers and footers.
Setting the PDF layout at space level
- Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar You'll need Space Admin permissions to do this.
- Choose PDF Layout.
- Choose Edit.
If your space uses the Documentation theme:
- Choose Browse > Space Admin from the header
Note: The Space Admin option appears only if you have space admin permissions, or if you're part of the 'confluence-administrators' group.
- Choose PDF Layout in space administration options.
- Choose Edit.
You can customise the HTML that is generated for the following areas when the space is exported to PDF:
- 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.
Customising the PDF Stylesheet
You can adjust the appearance of the PDF pages by customising the CSS in the PDF Stylesheet screen.
To get started, download the default CSS rules for 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 customisations are defined, the default CSS rules will be applied.
By default, the export does not include a title page, headers or footers. You can define these in the PDF layout.
To customise the PDF Stylesheet:
Setting a global PDF Stylesheet
- Choose the cog icon , then choose General Configuration under Confluence Administration
- Choose Look and Feel > PDF Stylesheet. The following screen allows you to enter and save CSS code that will render content on each page.
Setting a space PDF stylesheet
- Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar You'll need Space Admin permissions to do this.
- Choose PDF Stylesheet.
- Choose Edit.
- Enter your customisations.
If your space uses the Documentation theme:
- Choose Browse > Space Admin from the header
Note: The Space Admin option appears only if you have space admin permissions, or if you're part of the 'confluence-administrators' group.
- Choose PDF Stylesheet in the space administration options.
- Choose Edit.
- Enter your customisations.
The The 'PDF Export Stylesheet' page shows the current (e.g. customised) contents of your PDF stylesheet.
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 location 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:
- Attach the image to a Confluence page.
- View the list of attachments on that page, then right-click the image and copy its location.
- Paste the link into the appropriate
src=""attribute in your PDF Stylesheet, as shown above. - 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-macro rule to the PDF Stylesheet and set its display property to none:
div.toc-macro
{
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 © 2013, 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.
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"/>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
#pageNumrule selects the HTML element with the specified ID of "pageNum", which is thespanelement we created for the header or footer. - The
:beforepart of the selector is a pseudo class that allows the insertion of content before thespanelement is processed. - The
counter(page)is a function that returns the current page number as its content. - The
contentproperty 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.