How to Add a PDF to a Confluence Page (Step-by-Step Guide for 2025)

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.

All the Ways to Add a PDF to 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.

1. Upload a PDF as an Attachment (Native Confluence)

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.

2. Embed a PDF Using the Built-In PDF Macro

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.

3. Use the ikuTeam PDF for Confluence (Recommended)

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.

Quick Comparison

If your workflow involves reviewing PDFs, collecting signatures, giving feedback, or avoiding duplicate file uploads, the PDF Editor is the clear winner.

Method 1: Upload a PDF File to Your Confluence Page

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.

Step-by-Step: Upload a PDF to a Confluence Page

1. Open the Confluence page where you want to add the PDF

2. Click Edit to enter the page editor

3. Go to Insert → Files & images (or simply drag and drop the file into the editor)

4. Select your PDF file from your computer

5. Confluence uploads it and attaches it to the page

6. Once uploaded, the PDF appears as a link or thumbnail, depending on your editor settings

Method 2: Insert a PDF Using the Native PDF Macro

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.

How to Insert a PDF With the PDF Macro

1. Open your page and click Edit

2. Type /PDF in the editor

3. Select PDF from the macro list

4. Choose the attached PDF file from the dropdown

5. Click Insert

6. Publish the page. The PDF viewer will appear embedded

This adds an inline viewer with basic navigation controls so users can scroll through pages.

Configure the PDF Macro

The native macro includes a few useful configuration options. These settings help customize how the PDF is displayed on the page.

Key Parameters

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.

Limitations of the Native PDF Macro

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.

Method 3: Preview and Edit PDFs Using the ikuTeam PDF for Confluence app

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.

Step-by-Step: Using PDF Editor for Confluence

Step 1: Install ikuTeam PDF for Confluence

1. Go to the Atlassian Marketplace

2. Search for ikuTeam PDF for Confluence

3. Click Get it now

4. The app installs instantly (built on Atlassian Forge)

No extra configuration required, it works immediately.

Step 2: Add the PDF Editor Macro to Your Page

1. Open your Confluence page → Edit

2. Type /pdf editor
   or select it from the Insert menu

3. The macro automatically displays all PDFs attached to the page

4. 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.

Step 3: Preview PDFs on Your Page

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.

Step 4: Edit PDFs Directly in Confluence

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.

Step 5: Customize Layout (Headers, Width, Height, Visibility)

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.

Troubleshooting PDF Uploads and Embeds in Confluence

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.

PDF Doesn’t Display at All

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

Wrong PDF Is Shown

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

Preview Is Too Small or Cut Off

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

Cannot Edit PDF in PDF Editor

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

Missing Toolbar or No Preview

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

PDF Doesn’t Load or Shows an Error

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

Blank Preview When Using PDF Editor App

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.

Best Practices for Managing PDFs in Confluence

To keep your Confluence workspace clean, reliable, and easy for teams to navigate, follow these practical best practices when working with PDF files.

Use Clear, Descriptive Filenames

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.

Replace Attachments to Maintain Version History

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.

Keep PDFs Lightweight (Ideally Under 100MB)

Confluence supports large attachments, but heavy PDFs:

• Load slowly

• Reduce page performance

• Can cause preview failures

Compress files or split oversized documents before uploading.

Use PDF Editor for Confluence for Heavy Workflows

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.

Avoid Duplicate Uploads

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

Use Layout Options for Cleaner Pages

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.

FAQ: Adding PDF Files to Confluence

Why isn’t my PDF showing on the page?

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.

Can I embed multiple PDFs on the same Confluence page?

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.

What is the maximum PDF size I can upload?

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.

Can I edit PDFs directly in Confluence?

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.

Does the PDF Macro support all PDF file types?

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.

Are edits saved to the attachment automatically?

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.

Does Confluence create duplicates when updating a 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.

Can I annotate or sign PDFs inside Confluence?

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.

Conclusion: The Best Way to Add PDFs to Confluence Pages

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.