Adding a document to a site builder page

It can look fine in the desktop preview and show an empty box on a phone, so check it on both.

Site builders offer ways to put a document on a page, and the result can behave differently on a phone than in the editor.

An embedded document rendering on desktop and showing an empty box on a phone. (Illustration.)
An embedded document rendering on desktop and showing an empty box on a phone. (Illustration.)

The two built-in routes

Upload as a file. The builder stores the document and gives you a link. Tapping it starts a download. The visitor ends in a downloads folder, and on a work phone sometimes nowhere at all.

Embed in a frame. A fixed-height box holding the document. On a desktop it renders. On a phone some browsers do not render a PDF inside a frame and offer a download instead, and inside a short fixed box that offer may have nowhere to appear. The visitor can end up looking at an empty box.

Both are offered prominently, and both can fail on phones, which is why testing on a real device matters.

Method Desktop Phone
Upload as file Downloads Downloads
Frame embed Renders Can be blank
Preview image plus link Works Works
Rebuilt as a page Works Works

What to do instead

Preview image plus link. Export the first page as an image, place it, write two lines saying what the document is, and put a link underneath. Works on every device, loads immediately, and tells visitors what they are about to open before they open it.

Point the link at a displaying address. A document at an address opens in the browser on any device rather than starting a transfer. The difference is invisible until you watch somebody on a phone.

Rebuild it as a page if it is important. A price list or a menu read by every visitor deserves to be a page: searchable, readable at any width, correctable in place. More work, and it is the only option with no failure mode.

A page section with a first-page preview, two lines of description and a link.
A page section with a first-page preview, two lines of description and a link.

Fixed height is the other problem

An embed box has a height you choose, and no height suits both a laptop and a phone.

Too tall and phones scroll through empty space. Too short and the document is a letterbox nobody will read. Frames also trap scrolling, so a visitor trying to move down the page sometimes moves down the document instead.

There is no correct value, which is itself the argument against the approach.

Closely related: How to embed a PDF in HTML, and How to share a PDF as a link for the adjacent problem.

Put it at an address

Test on a real phone, avoid the frame embed, use a preview image with a link, point that link at an address that displays, and rebuild the content as a page when it matters enough.

Questions people ask

Why does the embedded document show a grey box on phones?

Some mobile browsers do not render a PDF inside a frame and offer a download instead, and inside a fixed-height embed there may be nowhere for that offer to appear.

What does the built-in document button do?

It uploads the file and links to it. Depending on the builder and the visitor's device, that link may open the document or download it.

What works on every device?

A plain link to an address that displays the document, or rebuilding the content as a page. Both avoid frames entirely.

Can I show the first page as a preview?

Yes, and it is a good pattern. An image of page one, a short summary, and a link underneath.

Does the embed hurt the page otherwise?

It adds weight and a fixed-height box that fits no screen well. A link costs nothing and fails nowhere.

Keep reading