embedpdf
Embed PDF files in Quarto HTML documents — including on mobile
The embedpdf extension adds a shortcode for embedding PDF files in your Quarto HTML documents and RevealJS presentations. On desktop it uses the browser’s built-in PDF viewer; on mobile — where embedded PDFs normally fail to render — it automatically falls back to PDF.js so your readers see the document either way. This guide walks through the available options.
Simple Usage
All you really need to give the pdf shortcode is the path to the PDF file you want to embed.
{{< pdf sample.pdf >}}
Remember to list the PDF file under resources in your document’s YAML header (or under project: resources: in _quarto.yml) so that Quarto copies it into your output site alongside the HTML.
Customization
In most cases you will want to customize the appearance of the embedded PDF. A few common options are built into the shortcode for convenience; for anything more, pass a CSS class and style it yourself.
Embed with width in pixels
{{< pdf sample.pdf width=600 >}}
Embed with width in percent
{{< pdf sample.pdf width=100% >}}
Embed with height in pixels
{{< pdf sample.pdf height=600 >}}
Embed with both width and height
{{< pdf sample.pdf width=600 height=400 >}}
Embed with a 1px border
{{< pdf sample.pdf border=1 >}}
Embed with a CSS class
{{< pdf sample.pdf class=myclass >}}
Supporting Mobile Browsers
Mobile browsers (e.g., Chrome and Firefox on Android) do not support the inline rendering of PDF objects: they show a blank box or a download prompt instead. To solve this, the extension includes a JavaScript-based PDF renderer, PDF.js.
By default (renderer=auto), each embedded PDF checks whether the browser can display PDFs inline (via navigator.pdfViewerEnabled). If it can, the browser’s native PDF viewer is used, exactly as before. If it cannot (e.g., on mobile), the PDF is instead drawn page-by-page onto the screen by PDF.js, complete with a small toolbar for zooming, page tracking, and downloading. Desktop visitors never download the PDF.js library; it is only fetched when a browser actually needs it.
Force the PDF.js renderer
Set renderer=pdfjs to always use PDF.js.
{{< pdf sample.pdf renderer=pdfjs height=500 >}}
Forcing renderer=pdfjs on your desktop is the easiest way to preview exactly what your mobile visitors will see, without needing a phone.
Force the native renderer
Set renderer=native to always use the browser’s built-in viewer.
{{< pdf sample.pdf renderer=native height=400 >}}
Use renderer=native for self-contained documents (embed-resources: true), where PDF.js cannot fetch the PDF by URL. Note that such documents still cannot render inline on mobile; readers there will get the download link.
Hide the PDF.js toolbar
{{< pdf sample.pdf renderer=pdfjs toolbar=false height=400 >}}
Setting defaults for the whole document or project
You can set default values for any shortcode option under the embedpdf key in your document YAML header or _quarto.yml, so you don’t have to repeat them:
embedpdf:
renderer: pdfjs
height: 600When JavaScript is Disabled
The viewer requires JavaScript to run. If a visitor has JavaScript disabled, the embedded PDF is replaced by a simple hyperlink to download the file. Adding a download button (button="...") gives those visitors a clearer call to action.