Adding PDF files to Confluence is a core part of many documentation workflows, whether you're sharing reports, contracts, technical manuals, signed documents, or onboarding material. The good news is that Confluence gives you several ways to work with PDFs. You can attach them, embed them, preview them, and with the right tools, even edit and annotate them directly inside Confluence.
Confluence's native features are great for simple uploads and basic viewing, but if your team needs reliable previews, clean layouts, or the ability to edit PDF files without downloading and re-uploading new versions, you'll want to use a dedicated app.
In this guide, you will learn every method available for 2026, including the modern approach that uses ikuTeam's PDF for Confluence app, the easiest way to view, edit, sign, and collaborate on PDFs directly inside a Confluence page. (On the Atlassian Marketplace itself, the listing is titled simply "PDF"; we'll use the more descriptive "PDF for Confluence" throughout this guide)
Quick answer: To add a PDF to a Confluence page, open the page in Edit mode and drag the file into the editor, this uploads and attaches it instantly as a downloadable link. To embed an inline preview instead of just a download link, type /PDF and insert the built-in PDF macro. For full editing, annotation, and e-signatures without leaving Confluence, use the ikuTeam’s PDF for Confluence app instead of the native macro.
When you want to upload or display a PDF file on a Confluence page, you have three main options. Each method offers different levels of functionality, from simple attachments to full in-page editing.
Below is a complete breakdown of the three approaches, what they do, when to use them, and their limitations.
This is the simplest and most common method. You upload the PDF directly to the Confluence page so users can download it.
How it works:
Pros
Cons
Best for: Simple downloads and reference materials.
The Confluence PDF macro embeds an inline, scrollable preview of an attached PDF directly on the page. Insert it by typing /PDF in the editor.
What it offers
Pros
Cons
Best for: Simple embedded viewing without editing.
For teams who need more than basic viewing, ikuTeam's PDF for Confluence app unlocks a complete PDF workflow directly on a Confluence page.
What it offers
Pros
Cons
Best for: Teams that need a true PDF workspace in Confluence, including legal, HR, product, engineering, finance, compliance, and operations.
|
Method |
Preview |
Editing |
Best for |
|
Attach PDF |
No |
No |
Downloads, simple sharing |
|
PDF Macro |
Basic |
No |
Inline reading |
|
PDF for Confluence |
Full |
Yes |
Collaboration, annotations, signing |
If your workflow involves reviewing PDFs, collecting signatures, giving feedback, or avoiding duplicate file uploads, PDF for Confluence is the clear winner.
Uploading a PDF to Confluence is the simplest way to make the file available to your team. This method adds the PDF as an attachment, which can later be previewed, embedded, or edited depending on the tools you use.
The PDF Macro is Confluence's built-in way to display an attached PDF directly inside a page. It creates an inline viewer so readers don't need to download the file just to see it.
This adds an inline viewer with basic navigation controls so users can scroll through pages.
The native macro includes a few useful configuration options. These settings help customize how the PDF is displayed on the page.
File Name: Select the specific PDF attached to the page.
Page Name: Choose a different page if the PDF is attached elsewhere. Useful for teams maintaining shared document hubs.
Height & Width: Adjust the display area of the embedded file by setting a fixed height for readability and choosing either a fixed pixel width or a full-width layout.
Show Page Navigation: Enable page-by-page controls for multi-page documents.
Show Border: Toggle an outer frame around the viewer for a cleaner structure.
While useful, the PDF Macro comes with significant restrictions:
If you need real preview controls, full-screen mode, or built-in editing, you'll get far better results with PDF for Confluence, which we cover next.
If you want more than a basic viewer, PDF for Confluence is the most modern and complete way to work with PDFs inside Confluence. It replaces the old download → edit → re-upload routine with a real in-page workflow.
With this app, you can:
This is the best option for teams handling contracts, reviews, design deliverables, legal documents, HR forms, or any file that requires collaboration.
No extra configuration required, it works immediately.
If your PDFs are already attached, they will appear instantly. If not, just upload them before inserting the macro.
The app offers a modern, flexible preview experience far beyond the native PDF Macro.
Preview features include:
This makes your Confluence page a functional PDF workspace instead of a simple file repository.
This is where the app becomes a true game-changer. You can:
How it works:
This is ideal for teams needing to review documents daily without leaving Confluence.
The macro includes powerful layout controls to match your documentation style.
Attachment Header Options
Preview Width
Preview Height
Default Visibility
These controls give you the flexibility to create clean dashboards, compact documentation indexes, or fully visible PDF pages.
PDF for Confluence is by far the simplest, most powerful way to preview, manage, and collaboratively edit PDFs directly inside your Confluence workspace.
Not every PDF starts as a Confluence attachment. Many teams keep contracts, reports, and reference documents in SharePoint, Google Drive, or Box, and only need Confluence to display or reference them, not host a duplicate copy.
For that scenario, a general-purpose connector is a better fit than a PDF-specific tool. On the Atlassian Marketplace today, these are listed as:
Once a PDF is inside Confluence as a native attachment, whether it started there or was brought in through one of these connectors, PDF for Confluence takes over for editing, annotation, and signing.
Even with the right method, PDFs in Confluence can occasionally behave unexpectedly. Here are the most common problems you may encounter and how to fix them quickly.
Cause: The file is not attached to the page or the macro points to the wrong file.
Fix:
Cause: Two attached PDFs share the same file name, causing Confluence to load the oldest one.
Fix:
Cause: Default PDF Macro size or layout mismatch.
Fix:
Cause: You don't have page edit permissions.
Fix:
Cause: Macro configuration hides elements or loads collapsed by default.
Fix:
Possible Causes:
Fix:
Cause: User is not authenticated, or Confluence cached a previous state.
Fix:
If problems persist, users can check page attachments, reconfigure the macro, or consult the PDF for Confluence documentation and the support portal for additional guidance.
To keep your Confluence workspace clean, reliable, and easy for teams to navigate, follow these practical best practices when working with PDF files.
Name your PDF file so users immediately understand their purpose. This prevents confusion and makes searching through attachments far easier.
Example: Project-Brief-Q1-2025.pdf instead of document.pdf.
When updating a PDF:
This is especially useful for policies, reports, and recurring documentation.
Confluence supports large attachments, but heavy PDFs:
Compress files or split oversized documents before uploading.
For teams handling PDFs daily, use PDF for Confluence because it supports:
This ensures your PDF workflows stay fast, secure, and version-clean.
Duplicate PDFs waste storage and cause version confusion. Instead:
Inside the PDF for Confluence macro, adjust:
This makes your pages more readable, especially when displaying multiple PDFs.
Following these best practices ensures your Confluence pages remain fast, clear, version-safe, and easy for teams to work with.
Common causes include:
If you're using ikuTeam's PDF for Confluence, ensure the macro is added and the file appears in the list of attached PDFs.
Yes. You can upload multiple PDFs and embed each one using:
Each file appears with its own preview and layout settings.
Confluence Cloud's default limit is 100 MB, but administrators may configure a custom limit. Larger files may load slowly or fail to preview; compress them when possible.
Not with Confluence alone. To edit PDFs, you need ikuTeam's PDF for Confluence, which lets you:
No downloads or re-uploads required.
The native PDF Macro supports standard PDFs, but:
For reliable previews and full functionality, ikuTeam's PDF for Confluence is recommended.
With the native PDF Macro, no editing is possible. With ikuTeam's PDF for Confluence: Yes. Edits are autosaved back to the original attached PDF.
No, unless you upload a new file with a different name. If you upload a file with the same name, Confluence stores a new version under the same attachment, keeping history clean.
Yes, but only using PDF for Confluence, which supports:
These features are not available in the native PDF Macro.
Adding PDFs to Confluence can be as simple or as powerful as your workflow requires.
And if your PDFs live outside Confluence altogether, in SharePoint, Google Drive, or another cloud drive, the SharePoint Connector, Google Drive Connector, and ikuTeam Files apps bring those same files into Confluence without duplicating storage.
For any team that works with documents, approvals, audits, contracts, design PDFs, reports, or annotated feedback, PDF for Confluence is the most efficient, modern, and reliable way to manage PDFs directly inside Confluence.
Try ikuTeam's PDF for Confluence for free today and turn static attachments into an integrated, collaborative document workflow.