How to insert PDF files in Confluence that actually look good

How to insert PDF files in Confluence that actually look good

How to insert PDF files in Confluence that actually look good
Inserting PDF files is a common action in Confluence. The native capabilities are limited, but there are alternative solutions to embed gorgeous pdf files.

Table of Contents

Introducing PDF Embed for Confluence

PDF files are a natural piece of your documentation. Unfortunately, the native capabilities make the navigation clunky and difficult in your Atlassian host application.

A great way to make a Confluence user happy would be to provide an easy and quick pdf app. One that integrates with your Atlassian wiki and gives flexibility for both publishing and reading any type of documents.


These are the highlights that explain why your users will love PDF Embed for Confluence:

  • Insert any PDF files in Confluence! Regardless of whether they’re on your hard drive, already attached to Confluence, or published somewhere online.
  • Choose exactly how you want users to view the pdf in your Confluence pages. Do you prefer a presentation mode? Or more traditional scrolling page after page?

Start embedding pdf documents that your colleagues can’t wait to read

Use cases for PDF files in 2021

PDF files don’t need introduction. Created in 1993 by Adobe as a way to easily share documents ready for printing regardless of operating system and application software, they have become the standard extension for finalized documents.

Hard copies have dwindled every year since the advent of the internet. And PDFs have lost some interest in favor of formats that are easier to scan and read on a screen. There are, however, no signs that the format will go away anytime soon.

Some of the most common use cases for pdf files include invoices, e-books, tickets, pre-printing proofs, contracts and agreements, as well as manuals, guidelines, and presentations. It’s time to supercharge your external visitors with the best experience browsing pdf documents in your most visited space. Particularly now that external collaboration for Confluence has just been announced!

Why attach PDF files in Confluence

Better search results

It’s a good idea to attach PDF files with business content to an organization’s Confluence wiki. In a traditional folder structure, search is limited to the file name. Now it will be easier for employees to find that employee handbook, slide deck, or customer contract in Confluence.

Access control

If a document is important, then it should be published in Confluence. Among other things, Confluence has the right permission schemes to make sure that documents can only be accessed by those who have the rights.

Preview attached files without downloading them

Many file and document management systems force users to download pdf attachments before they can be viewed. Confluence makes pdf files more transparent displaying the content without even a click.

Many important details can go unnoticed just because you’re hiding the document behind a card thumbnail!

See the difference in the image below. The same file is previewed on the left with the native macro, on the right with our app:

How to insert pdf files in Confluence
Which browsing experience do your users deserve?

Avoid multiple downloads

Downloading a pdf several times is a classic example of digital waste. Instead, insert a pdf in Confluence and ensure that the attachment is perfectly navigable for any stakeholder.

Problems with the Confluence Cloud PDF macro

While it’s great to create documentation that includes pdf files, you should know that there are some downsides to the native PDF macros in Confluence cloud.

These drawbacks include everything from missing functionality to a counterintuitive user interface and unexpected errors loading the file.

Non-intuitive UI to attach and preview pdf files

The standard flow for enabling pdf previews has two steps. First, you add the file to the page. Second, you embed it in the page. It’s not what anyone would expect, and Samantha is not the first confused rookie.

can't insert pdf in Confluence

Let’s have another look at the flow.

First, the pdf file must be attached to a Confluence page

Second, the existing attachment must be called from within the PDF macro to insert the preview in the page that you’re editing.

And in this second step, you must recall the exact pdf attachment by file name and page name.

Last but not least, the navigation controls in the pdf viewer are also not very clean. The arrows on the left and right of the document navigate between different documents stored in the same page, but they suggest a presentation.

resolution embed pdf in Confluence
The left arrow does not take you to a previews page. It takes you to an entirely different document.

It’s a bit disappointing that PDF files must be inserted in Confluence as attachments and not from a remote URL. If you need to embed a pdf that is hosted online, you will need to download it and reattach it.

Sometimes the PDF macro in Confluence Cloud just doesn’t work

It’s unfortunate, but judging by Atlassian Community threads like this and this, the native macro is not that reliable.

Plus, this is what I got when I gave it a go with several pdfs in my test instance. A big no:

error loading pdf in Confluence

Advantages of PDF Embed for Confluence over the native PDF macro

Here are some advantages of the new app for Confluence Cloud… beyond the important fact that it actually works.

Embed pdf from URL in Confluence

With PDF Embed for Confluence, you simply have more options.

Sure, you can upload a file. But that’s not the only way.

Whether it’s from your company OneDrive or from a third-party, all you need is an https URL.

…or embed local files and existing attachments

Not every PDF you need will be online. That’s why URLs are only one among three methods for publishing pdfs your Atlassian wiki.

Three methods for inserting pdf files in Confluence

The other two are quite obvious: you can select an existing attachment in your Confluence page, or upload a file from your local drive.

Version control for internal documents

Forget about uploading the last version of a document to Confluence, every single time.

Instead, you can simply use a permanent link that automatically serves the latest version of the file. This is really easy to do with Google Workspace. You don’t even need to convert your slides, docs or sheets to a pdf file.

Services such as Dropbox also support it (albeit with some workarounds). Even for complex workflows like updating the exported version of an Adobe Illustrator design!

View PDF attachments as presentations

PDF files have traditionally been viewed with a vertical scroll, but I can think of many cases where a presentation format suits the content better. PDF Embed for Confluence gives you the ability to decide how to display the document and how users should navigate through its pages.

Control whether a pdf can be downloaded or not

Toggle to dowload PDF

Sometimes you want users to save a document. Sometimes you don’t. Besides backing up confidentiality, one of the interesting advantages of blocking downloads is that nobody will be able to refer to an outdated version.

How to insert PDF files in Confluence

To start publishing PDF files in Confluence, you simply need to:

  • Read the Getting Started page to know every bit about the app
  • From your Confluence Cloud site, trigger the macro with the /pdf command or find the app in the macro menu, if that’s easier for you.
  • Select whether you will be embedding from a public https URL, an existing page attachment, or a local file
  • Decide how the pdf will be viewed, and any additional options
  • Hit Save!

How may we help?

We’re actively gathering requirements to improve this pdf Confluence integration. If there is any additional feature that would make your life easier, please contact us and we will discuss it internally in a matter of days!

Start your free evaluation of PDF Embed for Confluence now


Subscribe to our newsletter:

Related articles: