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 in 2025, including the modern approach that uses the ikuTeam PDF Editor for Confluence app, which is the easiest way to view, edit, sign, and collaborate on PDFs directly inside a Confluence page.
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:
Enter Edit mode on the Confluence page
Drag and drop the PDF into the editor or use the Files & Images button
Confluence attaches the file to the page
The PDF appears as a link users can click to download
Pros
Very fast
No configuration required
Works for all Confluence users
Cons
No inline preview (only download)
No editing, annotation, or signing
No layout control
Best for: Simple downloads and reference materials.
Confluence includes a macro that displays an inline PDF viewer directly on the page.
What it offers
Inline preview displayed inside the page
Page navigation (arrows, scroll)
Users don’t need to download the file
File must be attached to the same page
Pros
Native Confluence functionality
Allows basic in-page viewing
Good for documentation, manuals, long files
Cons
Limited viewer controls
No annotation or editing
Layout options are minimal
Sometimes unreliable with larger PDFs
Best for: Simple embedded viewing without editing.
For teams who need more than basic viewing, the ikuTeam PDF Editor for Confluence app unlocks a complete PDF workflow directly on a Confluence page.
What it offers
Real inline multipage preview
Collapsed or expanded preview styles
Full-screen viewer with navigation
Edit PDFs directly (no downloads)
Annotate, comment, highlight, and sign
Real-time collaboration (multiple editors at once)
Autosave inside the page
Works entirely with attached PDFs
Layout controls (header style, preview size, collapsed/expanded)
Pros
Most powerful option
Prevents version duplication (no re-uploads)
Perfect for signed documents, review cycles, contracts, markup work
Clean, configurable preview
Cons
Requires installation from Atlassian Marketplace
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 |
|---|---|---|---|
|
No |
No |
Downloads, simple sharing |
|
Basic |
No |
Inline reading |
|
Full |
Yes |
Collaboration, annotations, signing |
If your workflow involves reviewing PDFs, collecting signatures, giving feedback, or avoiding duplicate file uploads, the PDF Editor 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.
Open the Confluence page where you want to add the PDF
Click Edit to enter the page editor
Go to Insert → Files & images (or simply drag and drop the file into the editor)
Select your PDF file from your computer
Confluence uploads it and attaches it to the page
Once uploaded, the PDF appears as a link or thumbnail, depending on your editor settings
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.
Open your page and click Edit
Type /PDF in the editor
Select PDF from the macro list
Choose the attached PDF file from the dropdown
Click Insert
Publish the page. The PDF viewer will appear embedded
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:
No editing
You cannot modify or update the PDF inside Confluence.
No annotation or signatures
No ability to highlight, comment, stamp, or sign.
Limited preview features
No full-screen mode, no zoom controls, and no metadata view.
Minimal layout customization
Cannot adjust header visibility, preview density, or collapsible views.
Performance issues with larger files
Large PDFs can load slowly or fail to render consistently.
If you need real preview controls, full-screen mode, or built-in editing, you’ll get far better results with PDF Editor for Confluence, which we cover next.
If you want more than a basic viewer, ikuTeam 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:
Preview PDFs directly on the page
Open full-screen views
Edit, annotate, and sign documents
Collaborate in real time with teammates
Avoid clutter: no duplicate versions
Customize layout and display options
Work entirely inside Confluence with no local downloads
This is the best option for teams handling contracts, reviews, design deliverables, legal documents, HR forms, or any file that requires collaboration.
Go to the Atlassian Marketplace
Search for ikuTeam PDF for Confluence
Click Get it now
The app installs instantly (built on Atlassian Forge)
No extra configuration required, it works immediately.
Open your Confluence page → Edit
Type /pdf editor
or select it from the Insert menu
The macro automatically displays all PDFs attached to the page
Publish or configure the macro as needed
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:
Collapsed view by default (clean and compact)
Disclosure button to expand the preview
Inline preview with smooth scrolling
Full-screen preview for reading or presenting
Document info panel (file details)
Download button (if you want a local copy)
Edit button inside each preview for instant editing
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:
Edit PDFs directly
Annotate with highlights, comments, and shapes
Sign documents (e.g., internal approvals, HR forms)
Collaborate in real time with others
Rely on autosave to keep every change
Work with no file locking
Avoid download → edit → re-upload loops entirely
How it works:
Click Edit from the preview
The PDF opens in a new browser tab
Start editing, teammates join automatically
Close the tab when done; changes are saved immediately
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
Regular: large icon + details
Compact: small icon + filename only
Hidden: no header, preview shows immediately
Preview Width
Auto: adapts to page width
Custom: set a px/percentage width
Preview Height
Regular: standard 400px height
Custom: set any height you want
Default Visibility
Collapsed: hides preview until expanded
Expanded: preview is open on page load (required for hidden headers)
These controls give you the flexibility to create clean dashboards, compact documentation indexes, or fully visible PDF pages.
ikuTeam PDF Editor for Confluence is by far the simplest, most powerful way to preview, manage, and collaboratively edit PDFs directly inside your Confluence workspace.
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:
Open Attachments → check the PDF is listed
If using the PDF Macro, confirm the file name is correct
Reinsert the macro to refresh the reference
Cause: Two attached PDFs share the same file name, causing Confluence to load the oldest one.
Fix:
Rename the file locally (e.g., spec-v2.pdf)
Re-upload with a unique name
Update the macro reference if needed
Cause: Default PDF Macro size or layout mismatch.
Fix:
Increase height and width in the macro settings
If using PDF Editor for Confluence, open macro → adjust preview width/height
Switch header/visibility options for better layout control
Cause: You don't have page edit permissions.
Fix:
Confirm you have Edit access to the Confluence page
Ask an admin to grant edit permission
Reload the page afterward
Cause: Macro configuration hides elements or loads collapsed by default.
Fix:
Reopen macro settings → check Show toolbars
For PDF Editor app:
Ensure header is not set to Hidden unless intended
Switch preview from Collapsed to Expanded
Possible Causes:
PDF is corrupted
File failed during upload
PDF format or structure is unsupported by the native viewer
Fix:
Reupload the PDF
Try opening locally to confirm it’s valid
Use ikuTeam PDF Editor for Confluence for more reliable rendering
Cause: User is not authenticated, or Confluence cached a previous state.
Fix:
Refresh the page
Log in again if prompted
Clear browser cache for the Confluence domain if needed
If problems persist, users can check page attachments, reconfigure the macro, or consult the ikuTeam 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.
Example: Project-Brief-Q1-2025.pdf instead of document.pdf.
This prevents confusion and makes searching through attachments far easier.
When updating a PDF:
Upload a new file with the same file name
Confluence automatically creates a new version in the attachment history
You avoid clutter and keep a clean audit trail
This is especially useful for policies, reports, and recurring documentation.
Confluence supports large attachments, but heavy PDFs:
Load slowly
Reduce page performance
Can cause preview failures
Compress files or split oversized documents before uploading.
For teams handling PDFs daily, use the ikuTeam PDF Editor for Confluence because it supports:
Real previews
Full-screen viewer
Editing, annotating, and signing
Real-time collaboration
Autosave
No download/re-upload loops
This ensures your PDF workflows stay fast, secure, and version-clean.
Duplicate PDFs waste storage and cause version confusion.
Instead:
Replace the existing file
Or attach once and reuse that attachment
Or use the PDF Editor macro to manage multiple PDFs cleanly on the same page
Inside the PDF Editor macro, adjust:
Header type: regular, compact, hidden
Preview width: auto or custom
Preview height: regular 400px or custom
Default visibility: collapsed or expanded
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:
The PDF was not attached to the page
The PDF Macro is pointing to the wrong file name
The attachment has been renamed, and the macro wasn’t updated
The preview is collapsed, or the macro height is too small
If you're using ikuTeam PDF Editor 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:
The native PDF Macro, or
The ikuTeam PDF Editor for Confluence macro (recommended for multiple files)
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 PDF Editor for Confluence, which lets you:
Edit
Annotate
Sign
Collaborate in real time
Save changes automatically to the original attachment
No downloads or re-uploads required.
The native PDF Macro supports standard PDFs, but:
It does not support editing
It lacks annotation tools
It may struggle with very large or complex files
For reliable previews and full functionality, the ikuTeam PDF for Confluence app is recommended.
With the native PDF Macro, no editing is possible.
With ikuTeam PDF Editor 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 the ikuTeam PDF Editor for Confluence, which supports:
Highlighting
Comments
Drawing
Text boxes
Signatures
Real-time multi-user annotation
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.
Uploading a PDF is the fastest option when you just need the file attached to a page.
The native PDF Macro works well for quick, lightweight previews, but it’s limited. Has no editing, no annotations, and no customization, plus it struggles with larger files.
ikuTeam PDF Editor for Confluence delivers the complete solution:
Clean inline previews
Full-screen viewer
Real-time editing and collaboration
Annotation and signing tools
Customizable layouts
Autosave to the original attachment
Zero downloads or file duplication
For any team that works with documents, approvals, audits, contracts, design PDFs, reports, or annotated feedback, the ikuTeam PDF Editor for Confluence app is the most efficient, modern, and reliable way to manage PDFs directly inside Confluence.
Try the ikuTeam PDF Editor for free today and turn static attachments into an integrated, collaborative document workflow.