This page last changed on Dec 09, 2009 by ggaskell.

Confluence's PDF Export feature addresses the most highly voted improvement request for Confluence — more control over PDF exporting. Users can customise their PDF exports using a PDF Stylesheet, which is specific to each space in a Confluence installation. The following aspects of PDF exports can be customised:

  • Page and margin sizes
  • Headers and footers, each with customisable content such as page numbering
  • A customisable title page, which can incorporate images
  • Built-in support for table of contents with page numbering
Most PDF Stylesheet customisations are handled using Cascading Style Sheets (CSS), while customisations to headers, footers and the title page are handled using a combination of custom HTML and CSS. Hence, you should be familiar with these technologies (or may require some familiarisation with them first), before implementing the customisations you require.

On this page:

Customising the style of PDF exports

PDF export customisations are specific to each space.

To customise PDF exports, you will need the 'Space Administrator' permission which is assigned by a space administrator from the Space Administration screens. See Space Permissions or contact a space administrator for more information.

There are two areas that control the customisation of space-level PDF exports in Confluence. These are the 'PDF Layout' and 'PDF Stylesheet'.

PDF Layout

To access the PDF Layout for customisation,

  1. 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'. The 'Space Administration' view will open.
      'Space Admin' is only displayed if you are a space administrator.
  2. Click 'PDF Layout' in the left-hand panel. The main screen displays the current contents of your PDF Layout customisations. The PDF Layout is divided into the following three sections and allow for modifications to the:
    • PDF Space Export Title Page - containing custom HTML that generates the exported document's front title page.
    • PDF Space Export Header - containing custom HTML that generates headers throughout the exported content.
    • PDF Space Export Footer - containing custom HTML that generates footers throughout the exported content.
  3. Click the 'Edit' button and each of these three sections expands to an editable text box.
  4. Enter your customisations into each text box section as required and click 'Save' to save them.

PDF Stylesheet

To access the PDF Stylesheet for customisation,

  1. 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'. The 'Space Administration' view will open.
      'Space Admin' is only displayed if you are a space administrator.
  2. Click 'PDF Stylesheet' in the left-hand panel. The main PDF Export Stylesheet section on the right displays the current contents of your PDF Stylesheet customisations, which contains all CSS rule customisations applied to the pages in the space.
  3. Click the 'Edit' button and the 'PDF Export Stylesheet' section expands to an editable text box.
  4. Enter your customisations into the text box as required and click 'Save' to save them.
Refer to the Basic Customisations section for examples of typical customisations that can be added to your PDF Stylesheet. Once you are familiar with the implementation of basic PDF stylesheet customisations, you may wish to try out some Advanced Customisations.
  • If no PDF customisations are defined on the PDF Stylesheet screen, the PDF Stylesheet feature's default CSS rules will be applied to your PDF exports. Furthermore, no title page, header nor footer will be shown in these exports either.
    The PDF Stylesheet's default CSS rules are available for download. Any rule defined in (but not limited to) this file can be customised and added to the PDF Export Stylesheet section.

  • In general, you can override any default CSS rule by redefining it with your own customisations in the PDF Export Stylesheet section.

  • As shown in the Confluence to PDF topic, there are two PDF export methods:
    • Single pages via the 'Tools' menu -> 'Export to PDF' function on a page or blog post ('single page exports')
    • One or more pages in a space via the 'Advanced' view ('space exports')

  • All customisations, which include those made to your 'PDF Export Stylesheet', 'Title Page', 'Header' and 'Footer', apply to space exports. However, only the 'PDF Export Stylesheet' customisations inherently apply to single page exports.

  • To make your 'PDF Export Header' and 'Footer' 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 topic.

Basic Customisations

Page Customisations

Modifications to page and margin sizes are made in the @page CSS rule.

To make changes to this rule, you would implement the following type of code in the 'PDF Export Stylesheet' of 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. Hence, if this server was located in the US, the default paper size of your PDF export would be US Letter size (8.5 inches wide by 11 inches long). If the server was located in Australia, the default paper size would 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 the 'PDF Space Export Title Page' (of the PDF Layout) is not defined. The look and layout of the table of contents is completely customisable by defining the appropriate CSS rules in the 'PDF Export Stylesheet'.

For details about the CSS rules governing the default styles applied to the table of contents output in PDF exports, download the default CSS rules (from the link above) and examine the specific rules with toc in its name.

Disabling the Table of Contents

To prevent the table of contents being generated in your exported PDF document, add the div.toc rule to the 'PDF Export Stylesheet' section of the PDF Stylesheet and set its display property to none:

div.toc
{
display: none;
}

Change the Leader Character

The leader character is used to visually link the name of a heading in the table of contents list with its page number, which is usually aligned to the page's right-hand margin. By default, the leader character is the '.' (dot) character. However, it can be changed by customising the leader character CSS rule span.toclead:before and adding this to the 'PDF Export Stylesheet' section of the PDF Stylesheet.

To change this to a solid line, modify this CSS rule accordingly:

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

To change this it to spaces (that is, blank space), modify this 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 list difficult to read.

Adding a Title Page to PDF-Exported Space or Subsection

You can create a title or cover page for an PDF-exported space or subsection using XHTML. Use the 'PDF Space Export Title Page' section of the PDF Layout to do this. The following XHTML code example uses an inline CSS rule to generate a title page.

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

In the example above, an image called 'titlepage.png' will be centred in the middle of the page. This image is attached to a Confluence page and is referenced via its relative URL (that is, without the Confluence site's base URL component).

You can obtain the URL of an image attached to a Confluence page by viewing the list of attachments on that page and moving your mouse over the attachment's name. The URL of the image should appear in your browser's status bar or you can copy the link. Once you have this link, paste it into the appropriate src="" attribute within your PDF stylesheet and remove the first part of the URL up to the /download/... part.

Adding Headers and Footers

Headers and footers can be added to a PDF-exported space or subsection also using XHTML. Use the 'PDF Space Export Header' and 'PDF Space Export Footer' sections of the PDF Layout to create a custom header and footer, respectively. For simple headers and footers, plain text is sufficient. The following example added to a header or footer will create a simple copyright notice.

Copyright © 2009, Atlassian Pty Ltd.

Adding page numbering to a header or footer

To add page numbering to your documentation, you need to combine some customised XHTML in the header or footer along with some customised CSS in the 'PDF Export Stylesheet'.

First, create a header or footer with an empty span element and give it a unique id, for example pageNum (although this could be anything). This is the page number 'place holder' in your exported PDF document.

<span id="pageNum"/>

Next, create the following CSS selector rule for this empty span and add it to the 'PDF Export Stylesheet':

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

This will add a page number to your header or footer.

Analysing this CSS selector rule in more detail, the #pageNum selects the XHTML 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. Finally, the content property inside the rule 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 also 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 would be to find a selector for the HTML element produced by Confluence or the Confluence macro. Next you would add a CSS rule to the 'PDF Export Stylesheet' and your customisation would appear in the PDF export.

RELATED TOPICS

Advanced PDF Stylesheet Customisations


Document generated by Confluence on Dec 10, 2009 18:45