Customize Exports to PDF

Export Content to Word, PDF, HTML and XML

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Confluence provides a basic PDF export that you can customize and style to suit your needs. 

You need Space Admin permissions to customize PDF exports in a space, and Confluence Administrator global permissions to customize PDF exports for the whole site. 

On this page:

Related pages:

How it works

When someone exports a space to PDF, Confluence will apply any layout and styling directions it finds in the current space or set globally for the whole site. 

  • The PDF Layout allows you to add a title page to your PDF, and add a header and footer to all pages. 
  • The PDF Stylesheet allows you to change the look of the PDF. You can change just about anything, including the paper size, fonts and colours, spacing, and control behaviours like page breaks. 

Both the PDF Layout and PDF Stylesheet can be customized on a space by space basis, or globally for the whole site.  Space customizations will always completley override any global customizations. This means you can't mix and match and set some items globally and others at the space level. 

Limitations

There are a few limitations to be aware of:

  • Changes to the PDF layout only apply to space exports, not to single page exports (via 
    More options
     > Export to PDF).  
  • Confluence Server and Data Center process space exports slightly differently. This means that some options, like adding page numbers via CSS, aren't available in PDFs created with Data Center. We recommend selecting Include page numbers on the export screen if you need to number your pages. 
  • We provide a number of example customizations to get you started, however Atlassian Support can't help you with styling your PDFs or problems introduced by your customizations. If you're new to CSS, you might want to get help from an Atlassian Solution Partner, or check out a Marketplace app like Scroll PDF Exporter which has a WYSIWYG editor to help you produce beautifully styled PDFs. 

Change the PDF layout

The PDF Layout is where you add a title page, header, or footer to your PDF exports. The PDF layout fields accept HTML. You can include inline CSS in the HTML too.

To change the PDF layout for the whole site:

  • Go to Administration  > General Configuration > PDF Layout.
    You need Confluence Administrator global permissions to do this. 
    You need 
  • Choose Edit, then add your customizations in the Title, Header, or Footer fields.

To change the PDF layout for a specific space:

  • 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, then add your customizations in the Title, Header or Footer fields

PDF Layout examples

Here are some examples of things you can do in the PDF Layout.  The PDF layout can accept HTML and inline CSS. 

Title page

In this example we've added the title "Documentation for Confluence", a logo, and an additional title "Contents" above the table of contents.

<div class="fsTitlePage">  
 <img src="/download/attachments/169118009/atlassian_logo.png" />  
<div class="fsDocTitle">Documentation for Confluence</div>  
</div>   
<div class="tocTitle">Contents</div>

The logo image we've used is attached to a Confluence page in the same site. You can find out the attachment ID by right clicking the image on the page, and copying its location.

Header or footer

In this example we've added plain text to the footer with some copyright information, and included a link.

Created in 2018 by Atlassian. Licensed under a <a href="http://creativecommons.org/licenses/by/2.5/au/">Creative Commons Attribution 2.5 Australia License</a>.


Change the PDF stylesheet

The PDF Stylesheet allows you to change the appearance of your PDF. This includes things like paper size, fonts, colours, spacing, and other styling. 

To change the PDF stylesheet for the whole site:

  • Go to Administration  > General Configuration > PDF Stylesheet
    You need Confluence Administrator global permissions to do this. 
    You need 
  • Choose Edit, then add your CSS.

To change the PDF stylesheet for a specific space:

  • Go to the space and choose Space tools > Look and Feel from the bottom of the sidebarYou'll need Space Admin permissions to do this. 
  • Choose PDF Stylesheet.
  • Choose Edit, then add your CSS.

PDF Stylesheet examples

Here are some examples of common CSS overrides that you can use in your PDF Stylesheet. 

The default CSS rules will apply unless you have specified an override in the PDF Stylesheet.

Page size

The default page size is US Letter (8.5 inches wide by 11 inches long). To override this behaviour and specify a particular size, add a size property to the CSS @page rule.

For example to export your space in A4 size:

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

Page orientation

To change the page orientation of your PDF document, 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 an A4 PDF in landscape, 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

The default margins are 0.5".  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 like this:

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

To set margins to include a gutter for binding a printed document, you can 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 */ 
}

In the example above we've also used the :first pseudo-class to define different margins for the title page.

Page breaks

By default, each Confluence page will start on a new page in the PDF.  If you don't want each Confluence page to start on a new page, you can override the default page breaks using the following CSS:

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

This behaviour changed in Confluence 6.13. If you're using Confluence 6.12 or earlier, page breaks are not added before each page title. 

If you're using Confluence Data Center, you won't be able to change this behavior, as PDFs are generated page by page in the external process pool, and then combined together once all pages are complete.

Word wrapping

Long, unbreakable words or strings (such as a URL) will automatically wrap to fit the page width, or cell width if in a table. 

If you don't want words or long strings to break you can use the following CSS:

div {
    word-wrap: normal !important;
}

This may mean that the table formatting in your PDF is problematic, and very long content may overflow, and be cut off the page.

Title page

If you have added a title page in the PDF layout, you can use the following rules to change the appearance of the title page and 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;
}  

Table of contents

A table of contents is included by default when you export a space to PDF. It will appear at the start of the document, or after the title page, if you've configured a title page in the PDF layout. 

To omit the table of contents, use the following override:

div.toc
{
display: none;
}

The table of contents uses a leader character to visually connect the page title with it's page number. By default this is a dot.  Allowed values are dottedsolid and space. You can also use a string, for example leader(". . . ").

The example below uses solid line, instead of dots. 

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

Tables

When you export a page that contains a table, we'll reduce the width of the table columns as much as possible, so that the whole table fits comfortably on the page. Individual columns are resized to fit the contents of each column. 

If you prefer table columns to always be of equal width, you can use the following CSS:

table.fixedTableLayout {
    table-layout: fixed !important;
    width: 98% !important;
}

Any images in a table will be exported using the size set in the editor. If your table contains large images, part of the table may be cut off when exported to PDF.  To ensure that nothing is cut off, we recommend resizing images in the editor, so that the total width does not exceed about 600px (for an A4 page in portrait orientation). 

Alternatively you can use the following CSS to fit images to the available width:

table img.confluence-embedded-image {
    -fs-fit-images-to-width: 100%  !important;
}


Page numbers

The best way to add page numbers to your document is to select Include page numbers on the export screen. If you're using Confluence Server, and want more control over where page numbers appear, you can use CSS to add numbers instead. 

If you're using Confluence Data Center, you can't add page numbers using these methods, as PDFs are generated page by page in the external process pool, and then combined together once all pages are complete. Use the Include page numbers option on the export screen instead.

To add page numbers in the format "Page x of y" to the bottom of your page, add the following CSS to the PDF stylesheet:

@page
{
    @bottom-center
    {
        content: "Page " counter(page) " of " counter(pages);
        font-family: ConfluenceInstalledFont, Helvetica, Arial, sans-serif;
        font-size: 8pt;
    }
}

Alternatively you can add page numbers into the footer. This requires making a change in the PDF layout and the stylesheet. 

First, add an element in the PDF layout. In this example we'll call it pageNum:

<span id="pageNum"/>

Then, in the PDF stylesheet, style the pageNum element as follows: 

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


Headings

Heading sizes in the PDF export roughly match the sizes used on Confluence pages. You can easily override them as follows: 

h1 {
    /* Custom styling */
}
 
 
h2 {
    /* Custom styling */
}

This behaviour changed in Confluence 6.13.  In Confluence 6.12 and earlier, headings were demoted based on the position of the page in the page tree. Now headings are a consistent size on every page. 

Other formatting

You can use the stylesheet to customize the output of just about anything on the page, including 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. 

Last modified on Aug 22, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.