To embed a document, start by opening the “Share & Embed” action from the document’s page, or with the document selected. In either case, you’ll find the action in the right sidebar.
With the “Share & Embed” dialog open, find the “Customize Embed” action above the Embed Preview. Selecting it will reveal a the embed’s customization options. When changing an option, the Embed URL and HTML iFrame will update in response.
Customizing the embed sets these query parameters in the Embed URL we generate:
| Parameter | Values | Default | Description |
|---|---|---|---|
embed |
0, 1 | 1 | This argument provides an additional signal to our server that we should render an embedded page. It should always be included as a safeguard when constructing embed URLs. |
title |
0, 1 | 1 | Show a header with the document title and contributor name |
fullscreen |
0, 1 | 1 | Show a control to enter fullscreen view |
pdf |
0, 1 | 1 | Show a link to download the PDF file. |
onlyshoworg |
0, 1 | 0 | When showing the contributor, omit the username and just display their affiliation (e.g. "Washington Post”) |
zoom |
number, ‘width’, ‘height’ | width |
This controls the default zoom level of the embed. Any number value will be turned into a magnification level, with 1 being 100%, 1.25 being 125%, and so on. Providing width will default to Fit-Width, while height will default to Fit-Height. |
mode |
document, note, grid, text | document |
This controls the default view mode of the embed. By changing from the default to note, for example, the embed will display just the notes on the document by default. |
We also provide some options that apply to the attributes of the HTML iFrame we generate:
| iFrame Attribute | Default | Description |
|---|---|---|
| height | 600px |
An embed iFrame must have a fixed height |
| width | 100% |
By default, the iFrame will grow to fill its parent container’s width. |
You might notice that embeds are hosted at embed.documentcloud.org, while the main viewer and other pages live on www.documentcloud.org. What’s the difference?
Every page on www.documentcloud.org allows logged-in users to take some action — from uploading documents to managing projects to running add-ons. For that to happen, we need to make sure you see the freshest version of your data, so we limit caching. We also load a lot more data, because there’s a lot you can do.
Embeds, however, don’t need as much data and can live anywhere on the internet, including some of the biggest news sites in the world. That’s where our embed domain helps.
On embed.documentcloud.org, we don’t even try to log in users, and we only load data relevant to embedding a document (or a page, a note or a project). We also cache these pages much more aggressively.