Considering Confluence Cloud?
Get the high-level details of Confluence Cloud and available features by plan.
Additional PDF export settings
Note on @page Rules in Puppeteer PDF Generation
Certain @page properties may render differently due to limitations in Chromium's rendering engine used by Puppeteer. For best results and compatibility during PDF generation, please review the guide provided below for supported properties and best practices.
Unsupported @page properties and alternatives
1. @page :first
Issue: The :first pseudo-class for targeting the first page is not supported in Puppeteer.
Solution: Use body:first-of-type instead to target the content on the first page.
Replace:
1
2
3
@page :first {
/* your css here */
}With:
1
2
3
4
5
@media print {
body:first-of-type {
/* your css here */
}
}2. Background Images in @page
Issue: Background images applied directly to the @page rule are not rendered.
Solution: Apply background images to body or a specific container with position: fixed.
Replace:
1
2
3
4
5
@page {
background-image: url('background.jpg');
background-size: cover;
background-repeat: no-repeat;
}With:
1
2
3
4
5
6
7
@media print {
body {
background-image: url('background.jpg');
background-size: cover;
background-repeat: no-repeat;
}
}Why These Changes?
Puppeteer uses Chromium’s rendering engine, which prioritizes modern, screen-based CSS standards over older or print-specific CSS rules like @page. By using @media print with modern CSS, you can ensure compatibility across browsers and Puppeteer for consistent PDF rendering.
Summary Table of Replacements
Unsupported | Replacement |
|---|---|
@page :first | body:first-of-type |
Background in @page | Apply background to body |
Using Images and Fonts in Your Custom CSS
If you'd like to use any images or fonts in your custom CSS for Confluence exports, follow these steps to ensure they are accessible:
Upload Your Asset:
Navigate to a Confluence page in your space. For better organization, create a dedicated page named something like "Assets".
Upload your images or font files to this page.
Retrieve the Asset Link:
Once the asset is uploaded, click the More Actions menu (three dots) on the page.
Select Attachments from the dropdown menu.
Locate your uploaded file in the list of attachments.
Right-click on the file name and select Copy Link Address.
Use the Link in Your CSS:
Paste the copied link into your CSS file wherever an image or font is required. For example:
1 2 3 4 5 6 7@font-face { font-family: 'CustomFont'; src: url('https://your-confluence-instance.atlassian.net/wiki/download/attachments/SPACE_ID/filename.ttf'); } body { background-image: url('https://your-confluence-instance.atlassian.net/wiki/download/attachments/SPACE_ID/background.png'); }
Note: Ensure that the page containing the assets is accessible to the intended users of your Confluence content. Permissions on the asset page affect visibility.
Table of Contents Styling Limitations
It's important to note that while we're transitioning to a PDF V2, there are currently limitations in our implementation of table of contents (TOC) styling. Other CSS properties that were previously available will not work as expected in PDF v2 for now.
Currently supported TOC properties:
margin: Overall margin
margin-top: Top margin
margin-bottom: Bottom margin
margin-left: Left margin
margin-right: Right margin
size: Page size
display: Used to check if table of contents should be disabled (none)
If you do want to modify the following properties for the table of contents make sure to use the following selector.
1
2
3
4
div.toc-macro {
display: none;
/*other supported properties...*/
}Custom HTML cannot be added to the the table of contents at the moment.
Numbering Your Headings in CSS
If you want to add automatic numbering to your headings in Confluence exports, use the following CSS:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
body { counter-reset: heading1_counter; }
h1 {
counter-reset: heading2_counter;
}
h2 {
counter-reset: heading3_counter;
}
h3 {
counter-reset: heading4_counter;
}
h4 {
counter-reset: heading5_counter;
}
h1:before {
counter-increment: heading1_counter;
content: counter(heading1_counter) ". ";
}
h2:before {
counter-increment: heading2_counter;
content: counter(heading1_counter) "." counter(heading2_counter) ". ";
}
h3:before {
counter-increment: heading3_counter;
content: counter(heading1_counter) "." counter(heading2_counter) "." counter(heading3_counter) ". ";
}
h4:before {
counter-increment: heading4_counter;
content: counter(heading1_counter) "." counter(heading2_counter) "." counter(heading3_counter) "." counter(heading4_counter) ". ";
}
h5:before {
counter-increment: heading5_counter;
content: counter(heading1_counter) "." counter(heading2_counter) "." counter(heading3_counter) "." counter(heading4_counter) "." counter(heading5_counter) ". ";
}This will automatically number your headings in a hierarchical format (e.g., 1., 1.1., 1.1.1.) for better structure and readability.
Unsupported CSS Features in PDF Export
When using the new PDF export system (PDF v2), certain advanced CSS features are no longer supported due to limitations in modern browsers. Specifically, CSS properties like target-counter() and leader(), which were previously used to enhance the formatting of PDFs (such as adding page numbers to a table of contents), are not supported in current browser technology.
What Does This Mean for Your Content?
If your custom CSS includes rules like the following:
1
2
3
div.toc a::after {
content: leader('.') target-counter(attr(href), page);
}These rules will not work in the new PDF export system. As a result, features such as automatic page numbering in your table of contents or dotted leaders connecting headings to page numbers will not appear in the exported PDF.
Was this helpful?
Still need help?
The Atlassian Community is here for you.