How to insert PDF files in Confluence that actually look good

September 1, 2021

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?

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.

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.

Files can’t be inserted as links

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:

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.

Insert PDF files from a link…

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

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.