Customize layout for PDF exports in Confluence Cloud

In Q2 2023 we released an update to PDF export that renders Confluence pages more accurately. However, this update does not support the customizations described in this page and will fall back to the older method of PDF export that does not render Confluence pages as accurately if these customizations are detected.

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

Considerations

• PDF customizations use a combination of HTML and CSS
• PDF customizations are unique to each space
• PDF customization only applies to space exports (not single page exports via
  Tools >Export to PDF)
• To achieve a particular requirement in the exported PDF file, you make changes to the following:
  • The layout in PDF export, 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, color, and list numbering.

  For further customizations, see the Advanced PDF Export Customizations page.

  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 (
  1. 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:

  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.
     1. You can include inline CSS in the HTML.

     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 (
     1. Add CSS to render the same content on each page.

     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.
        1. Add CSS to render the same content on each page.

        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:

        1 2 3 4 5 6 7 8 9 10 11 12 13 CSS - PDF Stylesheet @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:

        1 2 3 4 5 6 7 8 9 10 11 CSS - PDF Stylesheet @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:

        1 2 3 4 5 6 7 8 9 10 11 12 CSS - PDF Stylesheet @page < size: 210mm 297mm; margin: 15mm; >

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

        1 2 3 4 5 6 7 8 9 10 11 12 13 14 CSS - PDF Stylesheet @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:

        1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 CSS - PDF Stylesheet @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:

        1 2 3 4 5 6 7 8 9 10 11 CSS - 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 field of the PDF Layout. The following example creates the title page and adds a title:

        

        1 2 3 4 5 6 7 8 9 10 HTML - PDF Layout: Title Page Section

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

        1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 CSS - PDF Stylesheet .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," 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:

        1 2 3 4 5 6 7 8 9 10 11 CSS - PDF Stylesheet 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:

        1 2 3 4 5 6 7 8 9 10 CSS - PDF Stylesheet span.toclead:before < content: leader(solid); >

        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.

        1 2 3 4 5 6 7 HTML - PDF Layout: Footer Section Copyright © 2013, Atlassian Pty Ltd.

        Page numbering

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

        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 4 5 6 7 8 HTML - PDF Layout: Footer Section

        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 :

        1 2 3 4 5 6 7 8 9 10 CSS - PDF Stylesheet div < word-wrap: 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 elements will become 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.