This page last changed on Mar 11, 2011 by pwatson.

This topic provides information and details on popular PDF stylesheet customisations. These expand upon the basic customisations described in Editing the PDF Stylesheet.

The information below is for advanced users. Customisations are not supported by Atlassian. Be aware that the advanced customisations described below require knowledge of certain parts of Confluence, and of CSS and HTML. This documentation is intended for advanced users. Some of the suggestions below are moderately complex. If you are having trouble understanding them we strongly suggest you ask an expert. We do not support any of the customisations described below. This means that the Atlassian support engineers will not be able to help you with these modifications, because even for them this kind of configuration can be tricky.

Page Customisations

Modifications to page and margin properties are made in the @page Cascading Style Sheet (CSS) rule. As described in Editing the PDF Stylesheet, all CSS rule customisations are implemented in the space's PDF stylesheet.

Changing the Page Orientation to Landscape or Portrait

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 PDF space exports in A4-sized landscape orientation, your @page rule might look like this:

@page
{
/*A4-sized pages in landscape orientation are 297 mm wide by 210 mm high*/
size: 297mm 210mm;
}

Customising Page Margins Separately

To set the margins of each side of a page independently of the other, you can declare each margin size in the @page rule using the following properties:

Properties Description
margin-top Margin height at the top of the page.
margin-bottom Margin height at the bottom of the page.
margin-left Margin width on the left of the page.
margin-right Margin width on the right of the page.

For example, to generate PDF space exports with top and bottom margins of 1 inch and left and right margins of half an inch, your @page rule might look like this:

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

Page Header and Footer Customisations

Adding Headers and Footers to Single Page Exports

As mentioned in Editing the PDF Stylesheet, custom headers and footers by default, only apply to space export' and not to exports of single pages. However, it is possible to add CSS rules to your PDF export stylesheet that allow custom headers and footers to appear in single page exports.

For custom headers, define @top-left, @top-center and @top-right rules within your @page rule. These rules apply respectively to content that appears on the left-hand side, centre and right-hand side of your page's header area.

For custom footers, define @bottom-left, @bottom-center and @bottom-right rules within your @page rule.

Add the following rules to add a document title at the centre of the header and a page number at the centre of the footer:

@page
/* Any page-specific properties */
{
    @top-center
    {
        content: "Document Title Goes Here";
        font-family: ConfluenceInstalledFont, Helvetica, Arial, sans-serif;
        font-size: 8pt;
    }
    @bottom-center
    {
        content: "Page " counter(page);
        font-family: ConfluenceInstalledFont, Helvetica, Arial, sans-serif;
        font-size: 8pt;
    }
    /* Any other page-specific rules */
}

Notes:

  • The font-family and font-size properties ensure that the header and footer text is rendered in the same default font style used for the body text, based on the default CSS rules.
  • It is not possible to use this method to insert images (stored as attachments within your Confluence instance) into the headers and footers of single page exports.

Adding Images to Headers and Footers

To insert an image into a header or footer, edit the header and footer sections of the PDF layout and use an HTML img element with src attribute. The src attribute refers to an image attached to a Confluence page. The image element is usually placed within a div element container.

For example, to add an image to the left of the header:

<div style="margin-top:10mm">
  <img src="/download/attachments/12346/header-image.png"/>
</div>

In the example above, the header includes an image called 'header-image.png'. The image is attached to a Confluence page and is referenced via its relative URL (that is, we use only the last part of the URL, excluding the Confluence site's base URL).

Follow these instructions to include an image on your PDF title page:

  1. Attach the image to a Confluence page.
  2. View the list of attachments on that page.
  3. Right-click the image and copy its location.
  4. Paste the link into the appropriate src="" attribute within your PDF stylesheet, as shown above.
  5. Remove the first part of the URL before the /download/... part.

To add an image to a footer, add similar HTML code consisting of an img element and src attribute. Incorporate the inline CSS property margin-bottom to separate the image from the bottom of the page if necessary.

Notes:

  • This code uses an inline CSS property in the style attribute to set formatting properties specific to this header image.
  • The margin-top:10mm property forces the image away from the top of the page by 10mm. This comes in handy when your header image is large enough to touch or spill over the top of the page.
  • Likewise, for footers, you can use the margin-bottom:XXmm property to force an image away from the bottom of the page by 'XX' mm.
  • Very large images can spill over into the body of a page or alter the position of text or other elements used within a header or footer. In such situations, it is recommended that you reduce the size of the image and then upload it to your Confluence site again. If you prefer to keep the image size and want to move the content lower instead, you can do so by configuring the margin-top properties in the @page CSS rule.
  • By default, a header or footer image is aligned to the left-hand side of the page. However, you can align this image to the centre or right-hand side of a page by adding either the text-align:center or text-align:right properties to your style attribute. For example, to align the header image to the right-hand side of the page, your style attribute would look similar to this: style="margin-top:10mm; text-align:right".

Page Selector Rules for Left- and Right-Hand Pages

If your PDF exports are destined for double-sided printed media (for example, books), you can define different customisations for left- or right-hand pages.

To do this, define two CSS pseudo-class page selectors as separate rules within the PDF stylesheet.

  • Use the :left psuedo-class with the @page CSS rule to define customisations for left-hand pages
  • Use the :right psuedo-class with @page to define customisations for right-hand pages.

You can use these page selector CSS rules in your PDF stylesheet to define alternating left and right margins to allow room for binding a double-sided document. For example:

@page :left {
  margin-left: 3cm;
  margin-right: 1.27cm;
  /* Any other left-hand page-specific properties and rules */
}

@page :right {
  margin-left: 1.27cm;
  margin-right: 3cm;
  /* Any other right-hand page-specific properties and rules */
}

Incorporating Other Fonts

Out of the box, Confluence provides Times New Roman, Helvetica or Courier fonts for use in PDF exports. You can incorporate your own fonts for use in PDF exports by declaring them within a @font-face CSS rule within your PDF export stylesheet.

The following CSS rule example shows how to embed the Consolas font into your PDF export:

@font-face {  
  src: url(file:///usr/share/fonts/Consolas.ttf);  
  -fs-pdf-font-embed: embed;  
}  
 
.code pre, .preformatted pre, tt, kbd, code, samp {  
  font-family: Consolas, monospace;  
  font-size: 9pt;  
}

The font path specified in the CSS must be the path to the font on the Confluence server.

Hiding Text from the PDF Output

This section describes a way to hide text from your PDF export. In other words, you can have text on the Confluence page that will not appear in the PDF export.

There are two stages:

  1. Follow the instructions to define the NoPrint user macro.
  2. Add the following CSS to your PDF stylesheet to make the PDF export recognise the NoPrint macro:
    .noprint {
    display: none ;
    }

Troubleshooting Tips

If styling is not working as expected, it is useful to look at the html source to which the css is applied. Whenever an export is created with multiple pages, the intermediary html is stored in the temp directory in Confluence's home directory. E.g.

<confluence-home>/temp/htmlexport-20110308-154047-1/export-intermediate-154047-2.html
Related Topics

Editing the PDF Stylesheet

Document generated by Confluence on Mar 16, 2011 18:20