PDF embed
Inline PDF viewer with a fullscreen expand button.
The pdf shortcode embeds a PDF document inline on the page using PDFObject. Readers can scroll through the document without leaving the page. An expand button opens the viewer fullscreen. Press Esc to return to the page.
The PDFObject script loads only on pages that contain a PDF embed.
File location
Where you place the .pdf file determines how it is loaded.
| Path style | Where the file lives | How it is loaded |
|---|---|---|
report.pdf (no leading /) |
Next to the page’s index.md as a page bundle resource |
Read at build time, embedded as a data URI, works on private sites |
/path/to/report.pdf (leading /) |
In assets/ at that path |
Read at build time, embedded as a data URI, works on private sites |
| Fallback (file not found in bundle or assets) | In static/ at that path |
Fetched at runtime, public sites only |
Build-time embedding converts the PDF to a base64 data URI and writes it directly into the HTML. No HTTP request is made when the reader opens the page, so the embed works on private GitLab Pages and any other auth-gated host. Keep individual PDF files under a few megabytes to avoid large HTML pages.
Usage
{{< pdf "report.pdf" >}}Or with an absolute path from assets/:
{{< pdf "/docs/files/report.pdf" >}}Live example
The demo file lives at exampleSite/assets/docs/files/sample.pdf in the theme repository and is embedded as a data URI at build time.
{{< pdf "/docs/files/sample.pdf" >}}Scroll through the pages inline, or use the expand button to open the viewer fullscreen and press Esc to return.
Parameters
| Parameter | Description |
|---|---|
| 1st positional | Path to the PDF file. Relative paths resolve as page bundle resources. Absolute paths (leading /) resolve from assets/. |
Notes
- The embed height defaults to 800 px and can be resized by dragging the bottom edge.
- If the browser does not support inline PDF embedding, PDFObject shows a link to open the file directly.
- Looking for the printable handbook and PDF export? See Print and handbook.