PDF formatting and best practices
Written by Benji Weiser
Updated at January 31st, 2025
Table of Contents
Below are some recommendations we have when uploading PDF content to the Pugpig Express CMS. If you upload your PDF content via XCago, they will optimise and send the files to us in the correct format, however it is still advised to follow these best practices to avoid any issues.
File type
We recommend using PDF/A over PDF. The A in PDF/A is for archive, and as the name suggests it's a much better format for preserving your digital content in the exact format you want it to be viewed in.
We also recommend either PDF 1.5, or lower, with no transparency, see below.
JPEG2000 Deprecation in Safari 18
Apple has deprecated support for JPEG2000 images in Safari 18, as outlined in the Safari 18 Release Notes. This change affects how PDFs containing JPEG2000 images are rendered on Apple devices running Safari 18 or later. Specifically:
- JPEG2000 images in PDFs will not be displayed when viewed in Safari 18 or later on macOS, iOS, or iPadOS.
- This may result in missing or blank images in PDFs that rely on JPEG2000 compression.
To ensure compatibility and avoid rendering issues, we recommend the following:
- Avoid Using JPEG2000 in PDFs: Replace any JPEG2000 images in your PDFs with more widely supported formats, such as JPEG or PNG.
- Test PDFs on Safari 18: Verify that your PDFs render correctly on Safari 18 or later by testing them on Apple devices.
File size
Optimised PDFs mean reduced data costs for you, and faster download times for your users. We would expect all individual pages to be at most 1MB in size. If your PDF pages are significantly larger, they should be optimised using a tool of your choice.
Maximum File Size
The maximum allowed file size for a single PDF upload is 1 GB. We are unable to split files that are larger than this.
Transparency
Occasionally we see issues with parts of pages missing, either text or parts of images and/or rendering artefacts. This is usually caused by layers with transparency. To avoid this we recommend that all PDFs are flattened before upload.
If you open the PDF file, that you've uploaded to the CMS, in another medium such as slack or your browser you may see the same issues as in the apps.
File name
If your PDF uploads are automated then we'll need to agree a name format with you that does not change. Please see the naming files section of our core PDF doc.