Customize layout for PDF exports in Confluence Cloud

Confluence and space admins can customize the PDF exports for individual spaces.

Customizing the PDF layout

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

Setting a global PDF layout:

1. Select the wheel icon () in the top-right corner to open Confluence administration.

2. Find Settings > Look and feel in the left-hand navigation.

3. Select PDF export.

4. Select Edit.

5. Enter your customizations in the Title, Header, and Footer fields.

   1. You can enter HTML and CSS that will be rendered on the PDF title page, as well as page headers and footers.

6. Select Save.

Setting the PDF layout at space level:

1. Go to the space in Confluence Cloud.

2. Select Space settings from the sidebar.

3. Select PDF export from the Look and feel card. 

   1. You'll need space admin permission to do this. 

4. Select Edit.

5. Add HTML to customize the Title, Header, and/or Footer fields.

   1. You can include inline CSS in the HTML.

6. Select Save.

Customizing the PDF stylesheet

You can adjust the appearance of the PDF pages by customizing the CSS in the PDF stylesheet field.

To get started, download the default CSS rules for the PDF stylesheet:  confluencedefaultpdf.css. Any rule defined in this file can be customized and added to the PDF Export Stylesheet field. Your customizations override any default CSS rule. If no customizations are defined, the default CSS rules are applied. 

By default, the export doesn't include a title page, headers, or footers. You can define these in the PDF layout. 

Setting a global PDF stylesheet

1. Select the wheel icon () in the top-right corner to open Confluence administration.

2. Find Settings > Look and feel in the left-hand navigation.

3. Select PDF export.

4. Select Edit.

5. Enter your customizations in the PDF stylesheet field.

   1. Add CSS to render the same content on each page.

6. Select Save.

Setting a space PDF Stylesheet

1. Go to the space in Confluence Cloud.

2. Select Space settings from the sidebar.

3. Select PDF export from the Look and feel card. 

   1. You'll need space admin permission to do this. 

4. Select Edit.

5. Enter your customizations in the PDF stylesheet field.

   1. Add CSS to render the same content on each page.

6. Select Save.

Example Customizations

This section provides examples of typical customizations you can add. You can also check out Advanced PDF Customizations.

Page Size

The default page size is based on the location of your Confluence instance. For example, if this instance 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 instance 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:

or

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 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:

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

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

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:

Title page

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

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

In the example above, the title page includes an image called "titlepage.png," centered in the middle of the page. The "590719" in the src attribute is the ID 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's 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:

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:

Headers and footers

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

Page numbering

To add page numbering, you need to combine customized HTML with customized CSS in the PDF stylesheet field.

1. Layout fields 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 placeholder for the page number.

   1 2 3 <div style="width: 100%; text-align: center; font-size: 12px; padding: 10px; font-family: Arial, sans-serif;"> <span id="pageNum"></span> </div>

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

   1 2 3 4 5 6 7 #pageNum:before { content: "Page " counter(page); font-weight: bold; font-size: 12px; color: #333; font-family: Arial, sans-serif; }

Analyzing 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:

General formatting

You can use the stylesheet to customize 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 customizing 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 customization will appear in the PDF export.

• 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 customization is limited. We support the mechanism for customizing 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 customizations.