Download the PHP package justinholtweb/craft-book without Composer

Book

Embed any document in Craft CMS. PDFs, Word, Excel, PowerPoint, OpenDocument, RTF, CSV, Markdown, JSON, text, code, images, audio and video — from a Craft asset or a URL, in a Twig template or in rich text.

Reference point: the WordPress plugin Embed Any Document. Same ground, done the Craft way — an element with a reference tag rather than a shortcode, assets as first-class sources, and a Twig API that is the point rather than an afterthought.

Free. No editions, no licence key.

The problem

Four things go wrong when you put a document on a page, and Book exists for all four.

A PDF ends up as a link. "Download our brochure (PDF, 4 MB)" is not an embed, and the reader has to leave the page to find out whether it was worth downloading.

A .docx cannot be shown by any browser. Somebody has to render it, which in practice means Google or Microsoft — which means the file's URL leaves your site, usually without the reader being asked.

Private documents have no URL at all. An asset in a volume with no public URLs has nothing to hand a viewer, so the usual answer is "make the volume public". That is the wrong answer.

The interesting formats are text. A CSV, a Markdown file, a JSON export — these need no viewer at all. They need a server willing to read them and write a table.

Book never makes an outbound HTTP request

That is an architectural promise, not a side effect, and it is worth stating before anything else:

• Third-party viewers are URLs, not fetches. Google's and Microsoft's viewers are <iframe src> values that the reader's browser loads. Book only ever writes the URL.
• Inline rendering reads assets, never URLs. Book's own renderer reads bytes out of your asset volume. An external URL cannot be inlined, and Book says so instead of trying.

So there is no SSRF surface, no host allowlist to maintain, no fetch timeouts and no proxy settings. The one thing to be aware of is the flip side: a third-party viewer means a third party downloads your file, and Book is explicit about that everywhere it comes up.

Install

Craft 5.3+, PHP 8.2+. No runtime dependencies beyond Craft's own.

Twig

The one to reach for takes anything:

Or the filter and function, which are the same thing:

Options are passed as a hash and can override anything the document was configured with:

The rest of craft.book

craft.book.resolve() is the interesting one. It answers "what will actually happen here", which is the same answer the control panel shows an author:

Rich text

A document in the library has a handle, and its reference tag renders anywhere Craft parses reference tags — CKEditor, Redactor, or any other HTML field:

That is the whole integration. The CKEditor toolbar button, the Redactor plugin and the shared picker are editing affordances: they help an author write the tag. Turn them all off and existing documents keep rendering, because rendering was never the editor's job.

Pasting a link to a file (…/report.pdf) on its own line adds it to the library and inserts its tag, deduplicating by file so ten pastes make one library entry.

The five viewers

auto — the default — picks the first viewer the format supports that is actually usable here: allowed by your settings, reachable by whoever has to fetch it, and readable if Book is doing the reading. It will not hand a .ddev.site or .test URL to Google, because the result is a viewer box full of apology, and that is the single most common way a document embed fails on staging.

When auto cannot use a richer viewer, or when your explicit choice cannot be honoured, Book says why — on the edit screen before publishing, in craft.book.resolve(), and on the page itself when devMode is on. Set fallback: false to make an impossible choice become a download card rather than quietly becoming a different viewer.

Inline rendering

The formats that are secretly text get rendered by Craft itself, with nobody else involved:

• CSV / TSV → a table. Delimiter sniffed, quoted commas respected, Windows-1252 repaired, BOM stripped, row limit honoured and admitted to.
• Markdown → prose, run through HTML Purifier — Markdown allows raw HTML by design and these files come off an upload volume.
• JSON → pretty-printed.
• Text, logs, code, XML, YAML → an escaped, scrollable block.

This works for private assets, costs nothing at the network layer, and is usually better than what a document viewer would have produced.

Private documents

An asset in a volume with no public URLs is served through Craft, on a route Book mints a signed token for. That is what makes the browser's own PDF viewer and Book's inline rendering work without making the volume public.

The rule the route rests on: a file with no public volume URL is never served without a token Book itself minted. The token carries the access rule, HMAC-signed, so it cannot be edited into something it was not signed for. An unsigned request only ever reaches a file that is already published at its own volume URL, where serving it changes nothing.

Per document:

• access: 'public' — anyone with the link (the link is an unguessable UID)
• access: 'login' — a logged-in user; guests are sent to the login screen

Site-wide, in the settings:

• Serve assets through Craft — force every file onto Book's route, even public ones
• Sign file URLs — add an expiring signature to them

One consequence worth knowing before you turn signing on: Google and Microsoft fetch the file from their own servers, so a signature that expires takes those embeds with it. Book warns about that combination rather than letting you find out later.

Fields

Document — a file configured where it is used. Pick an asset or paste a URL, and choose from whichever options the field's settings expose. {{ entry.brochure }} renders it.

Documents — a plain relation field to library documents. Everything you expect from a relation field works, because it is one.

Customising the markup

Every surface renders through one template. Put your own at templates/_book/document.twig and it wins, with the same variables Book's own gets: id, label, source, format, options, viewer, resolution, classes, stageStyle, frameAttributes, config, consent, card, inlineHtml, texts and the document element when there is one.

The stylesheet is small and expressed entirely as custom properties on .book:

Both the stylesheet and the runtime can be switched off in the settings if you would rather ship your own. A document with no runtime still shows its frame; what you lose is click-to-load, the load timeout, fullscreen and print.

The front-end runtime

Four jobs, no dependencies, ~5 KB:

1. Click-to-load. The frame is parked in a <template>, which is the only markup that genuinely defers the request — a hidden iframe still loads, which is the mistake most consent banners make.
2. A load timeout. A viewer that cannot reach your file answers 200 OK with an apology page, and a blocked frame says nothing to its parent at all. Past the deadline, Book shows the file itself instead of a blank box.
3. Fullscreen, on the stage rather than the frame.
4. Print, which prints the document for a same-origin frame and the page otherwise.

Settings

Permissions

book:viewDocuments, with book:manageDocuments and book:deleteDocuments nested under it.

Not in scope

• Server-side conversion. Rendering a .docx to HTML on your own server means LibreOffice or Gotenberg, which is a different plugin with a very different dependency footprint.
• Fetching external URLs. See the promise at the top.
• Full-text extraction of document contents for search.

Licence

The Craft License. See LICENSE.md. Book is free: no editions, no licence key, and no licensing code in the plugin.