This page last changed on Sep 17, 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

To customise the PDF Stylseheet, 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.

To customise the PDF Stylesheet,

  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 screen displays the current contents of your PDF Stylesheet customisations. The PDF Stylesheet is divided into the following four sections and allow for modifications to the:
    • PDF Export Stylesheet - containing all CSS rule customisations applied to the pages in the space.
    • PDF Export Title Page - containing custom HTML that generates the document's title page.
    • PDF Export Header - containing custom HTML that generates headers throughout the document.
    • PDF Export Footer - containing custom HTML that generates footers throughout the document.
  3. Click the 'Edit' button and each of these four sections expands to an editable text box.
  4. Enter your customisations into each section as required.
    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' section of the space's 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 Export Title Page' 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 space's 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 space's 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 Export Title Page' section of the space's PDF Stylesheet 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.

Adding Headers and Footers

Headers and footers can be added to a PDF-exported space or subsection also using XHTML. Use the 'PDF Export Header' and 'PDF Export Footer' sections of the space's PDF Stylesheet 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 Nov 05, 2009 23:36