How To Use

Three Ways to Embed

The same viewer reaches your page by three routes. They share one settings surface, so the choice is about where you want the settings to live, not about what you can do.

The three routes

What is identical

Every setting on a document has a matching panel on the block. The plugin renders both through the same block, so a document placed by shortcode and a block placed on a page produce the same markup and the same behavior.

What is not

• Download counts and leads are per document. The Download Stats panel and the leads filter key off the document ID, so a block on a page has nowhere to report them.
• Reuse. Change a document once and every shortcode that points at it updates. A block is local to its page.
• Lightbox mode currently needs the block. See the limitation on the Modal Pop Up page.

The Document Configuration Panel

Everything about how a document looks and behaves lives in one panel on the document edit screen, split into eight tabs. This page is the map; each tab has its own page.

The eight tabs

Work through them in order

The tabs are ordered the way the settings depend on each other. The General tab decides the engine, and the engine decides which of the Controls options apply at all. The Toolbar tab switches the download button on, and Download Management configures the button that is already switched on.

The same settings on the block

The block sidebar carries the same options, but it splits the General tab across three panels and lists them in its own order. This table is in the order the sidebar shows them.

Every settings page in this guide carries an editor switch at the top. Flip it and the screenshots and the location line change with it, so you are always looking at the panel you are actually in.

Live Preview While You Edit

You do not have to publish a document to see how it will look. A Live Preview box sits below the Document Configuration panel and renders the document exactly as visitors will see it, using the settings currently on screen, including ones you have not saved.

The preview bar

• Desktop / Tablet / Mobile – switch device widths to check your responsive width and height.
• Refresh – redraw the preview after a change.
• A status line reads Preview up to date once the render matches the settings on screen.
• Click the Live Preview heading to collapse or expand the whole box.

Nothing is saved by previewing

The preview deliberately reads the unsaved values in the panel, so you can try a setting, look at it, and change your mind. Your changes only reach visitors when you press Update.

What it covers

Live Preview is in the free version and works with all four viewer engines. The block editor has no separate preview box because the block renders the document on the canvas itself.

The Editor Sidebar

The right-hand column of the document editor carries two panels of its own, under Publish.

Download Stats

A running count for this document: Total Downloads and Total Leads. The download total comes from the counter the download button increments; the leads total counts rows captured by the email gate for this document.

View Leads opens the Download Leads screen with the document filter already applied, which is the quickest way to see who downloaded this particular file. See Leads Dashboard.

Page Builder Support

A reminder that the shortcode under the post title works in Elementor, Divi, Bricks, WPBakery, Beaver Builder, Oxygen and Breakdance. Copy it from the field beneath the title and paste it into any builder’s shortcode or text widget.

The Document Embed Block

If you build pages in the block editor you can skip the document post entirely. Add the Document Embed block to your page and configure it in the block sidebar.

Adding the block

1. Edit a post or page and add the Document Embed block

   Edit a post or page and add the Document Embed block. Search for Document, PDF, Embed or Viewer.

2. Open Document Source in the sidebar and upload a file

   Open Document Source in the sidebar and upload a file or paste a URL.

3. Pick a Viewer engine, then work through the remaining

   Pick a Viewer engine, then work through the remaining panels.

The block renders the real document on the canvas as you go, so what you see is what visitors get.

Where the block’s defaults differ

The block ships slightly different starting sizes than a document, because a block usually sits in a full-width column.

Document or block?

Use a document when the same file appears in more than one place, or when you want download counts and leads tracked for it. Use the block for a one-off embed on a single page. See Three Ways to Embed for the full comparison.

General

The General tab holds the three settings everything else depends on: which file you are showing, which engine renders it, and how big the viewer is on each device.

The steps below are given for both routes. Pick the one you use.

The document file

Supported types include PDF, Word (.doc, .docx), Excel (.xls, .xlsx), PowerPoint (.ppt, .pptx), Apple Pages, PSD, images and code files: more than ten formats in total.

Viewer

All four engines are in the free version. See Viewer Engines for the full comparison.

Width and height

The viewer’s size is set per device, so a layout that works on desktop does not have to be a compromise on a phone.

Display options

Two smaller options finish the tab. On the block they live in the Security & Restrictions panel.

Viewer Engines

Document Embedder can render the same file in four different ways. The engine you pick decides how the document looks, how fast it loads, and which of the plugin’s other options apply to it, so this is the first setting to get right.

The steps below are given for both routes. Pick the one you use.

The four engines

All four are available in the free version.

Default

Renders the file through the Google Drive viewer. This is the only engine that handles non-PDF files (Word, Excel, PowerPoint, Pages, PSD and the rest), so it stays the right choice for a mixed document set. Because the file is displayed inside Google’s own frame, the plugin’s Controls, Interactive Overlays and Secure Document Delivery options do not apply to it. It needs a publicly reachable file URL.

Custom PDF (PDF only)

Renders PDFs on your own server with a bundled PDF.js engine, so nothing is sent to Google. It is the fastest and most configurable engine, and the only one that offers Default Zoom and a Horizontal Scrollbar. Pick it for reports, manuals and anything long or private.

Flipbook (PDF only)

Presents the PDF as a book with a page-turning animation. It uses a 3D page curl where the browser supports WebGL and drops to a flat 2D page turn where it does not, so every visitor gets a working flipbook. Suits brochures, magazines, catalogues and portfolios.

Slider (PDF only)

Shows one page at a time as a swipeable slideshow, with no page-turn animation. Good for slide decks, one-page-per-idea documents, and mobile-first layouts where a flipbook feels heavy.

What each engine supports

Which one should I use?

• A mix of file types, or a Google Drive or Dropbox file: Default.
• A long PDF report, manual or whitepaper: Custom PDF.
• A brochure, catalogue, magazine or portfolio: Flipbook.
• A slide deck, or a document most people read on a phone: Slider.
• You need overlays, role-restricted viewing or secure delivery: Custom PDF, Flipbook or Slider.

Controls

The Controls tab fine-tunes how the reader behaves once the document is on screen: what chrome is visible, which page opens first, and how much of the file is rendered at a time.

The steps below are given for both routes. Pick the one you use.

Every option

Choosing a Default Zoom

Availability at a glance

Toolbar

The toolbar carries the document’s name and its download button. This tab decides whether it appears, where it sits, and how it is colored.

The steps below are given for both routes. Pick the one you use.

What appears in the bar

Color and theme

The order things happen in

1. Switch on Show Download Button here, on the Toolbar tab

   Switch on Show Download Button here, on the Toolbar tab.

2. Set the label, behavior, limit and access rules under

   Set the label, behavior, limit and access rules under Download Management.

3. Come back here to choose Toolbar Position and the theme

   Come back here to choose Toolbar Position and the theme.

Skipping the first step is the most common reason a download button does not appear. Download Management configures a button that is already switched on; it does not switch one on.

Modal Pop Up (Lightbox)

Lightbox mode keeps a page clean by opening the document in a focused popup instead of embedding it inline. You choose what the visitor clicks to open it.

The steps below are given for both routes. Pick the one you use.

Turning it on

Button trigger

These four fields appear when the trigger is Default Button.

Image trigger

These fields appear when the trigger is Click Featured/Preview Image. Use a document cover, a first-page thumbnail or a mockup: the image itself becomes the link.

Custom element trigger

Download Management

This tab covers everything about the download button: its label, what clicking it does, how many times it may be used, who may use it, and whether a visitor has to hand over an email address first.

The steps below are given for both routes. Pick the one you use.

The button itself

Who may download

Email Gate

How the per-IP limit is counted

The limit counts rows already recorded against the visitor’s IP address for this document. That means the counter and the limit share one record, so a visitor who has downloaded a file three times is at three whether they went through the gate or not.

Access & Security

Document Embedder controls access at two independent levels, and it matters which one you reach for. Download Access gates the button. View Access gates the document.

The steps below are given for both routes. Pick the one you use.

Two levels, one decision

In short: use Download Access when people may read but not keep the file, and View Access when they should not see it at all.

Every option

If your site uses a full-page cache

Most caching plugins offer both a never cache these pages list and a do not cache for logged-in users switch. Either one is enough.

What these settings do and do not do

They do keep the file URL out of your page’s HTML for visitors who are not allowed to view the document, and they re-check permission on every request rather than trusting anything stored in the browser.

They do not encrypt the file on disk, and they cannot stop someone who is legitimately allowed to view a document from screenshotting or re-sharing what they see. For stronger guarantees, pair View Access with a membership plugin.

Interactive Overlays

Overlays let you place your own content on top of a PDF page without editing the PDF: a note in the margin, a highlight over a paragraph, a clickable link across a logo, or a call to action beside a price table.

The steps below are given for both routes. Pick the one you use.

Each overlay is positioned as a percentage of the page rather than in pixels, so it stays exactly where you put it whether the reader is on a phone, on a desktop, or zoomed to 200%.

Before you start

Overlays need a PDF document on the Custom PDF, Flipbook or Slider engine.

Adding your first overlay

1. Open Interactive Overlays and click Add Overlay

   Open Interactive Overlays and click Add Overlay. A new row opens, already set to Note on page 1.

2. Pick the Page Number

   Pick the Page Number. When the plugin can read the PDF’s page count you get a dropdown listing every page; otherwise you type the number.

3. Choose a Type: Note, Highlight, Link or Call to Action

   Choose a Type: Note, Highlight, Link or Call to Action.

4. Set the position with the four sliders: Left (X %), Top

   Set the position with the four sliders: Left (X %), Top (Y %), Width (%) and Height (%).

5. Fill in the type’s own field

   Fill in the type’s own field. Links take a Link URL; Notes and CTAs take Content. Highlights need nothing.

6. Watch the Live Preview below the panel to check the

   Watch the Live Preview below the panel to check the placement, then press Update.

The four overlay types

How positioning works

All four sliders are percentages of the page, measured from its top-left corner. Left (X %) is the distance from the left edge, where 0 is flush left and 50 is the middle. Top (Y %) is the distance from the top edge. Width (%) and Height (%) are the size of the box.

Because nothing is measured in pixels, an overlay at 50% / 50% sits in the centre of the page at every screen size and zoom level. The sliders move in steps of 0.5, which is fine enough to line up with a column of text.

Every overlay field

Reordering, duplicating and removing

• Move up and Move down reorder the list.
• Duplicate copies an overlay including its position. It is the fastest way to put the same CTA on several pages: duplicate, then change only the page number.
• Remove deletes it. You can remove every overlay; a document with none simply renders as usual.

Row titles read as type and page number, for example Call to Action, page 12, so a long list stays scannable without opening each row.

What you can put in an overlay

Note and Call to Action overlays accept basic HTML: links, bold, emphasis and line breaks, so you can write a short formatted message. Scripts and event handlers are stripped when the document is saved.

Keep the text short. An overlay is sized as a share of the page, so long copy either overflows its box or forces a box big enough to cover the content underneath.

Performance & Reliability

Two settings control how a document affects your page speed and what happens if a viewer fails to load. Unlike the Controls panel, both apply to every engine and every file type.

The steps below are given for both routes. Pick the one you use.

Both options

Recommended settings by situation

Building a Library

A Document Library shows a collection of files on one page as a searchable, sortable grid of cards. It is a separate module from a document: its own editor, its own settings and its own shortcode.

Find it at: Document Embedder → Document Library. Libraries render through [document_library id="12"].

Building one

1. Go to Document Embedder -> Document Library and click

   Go to Document Embedder → Document Library and click Add New Library.

2. Give the library a name in the field beside Edit

   Give the library a name in the field beside Edit Document Library.

3. On the Upload Items tab, add your files

   On the Upload Items tab, add your files.

4. Work through the Header, Toolbar Box, Document Box and

   Work through the Header, Toolbar Box, Document Box and Library Container tabs to style it. The preview beside the settings updates as you go.

5. Click Save, then copy the shortcode from the field at

   Click Save, then copy the shortcode from the field at the top of the editor and paste it onto any page.

[document_library id="1896"]

Five tabs, working from the outside in

The tabs follow the layout of the rendered library, from the outside in.

How many files

How library documents open

When a visitor opens a document from a library, PDFs stored in your own media library are rendered with the plugin’s bundled PDF.js viewer rather than the Google viewer. They open faster and more reliably, which is what fixed the intermittent blank-frame failures in earlier versions.

This is automatic and needs no setting. Files hosted elsewhere, and non-PDF file types, continue to use the Google viewer.

Upload Items

The Upload Items tab is where the library’s files come from, and where you write the title, author, description and size that visitors see on each card.

Three ways to add a file

Document details

Every file you add gets four editable fields. These are what visitors see on the card, and what the search box looks through.

Your Uploaded Documents

A table of everything in this library. Use it to rename a file, edit its details, reorder the list or delete an entry. Tick several rows to act on them together, or use the header checkbox to select the page.

Header

The Header tab controls the title block that sits above the library grid: whether it appears at all, what it says, and how it looks.

Content

Styles

Toolbar Box

The Toolbar Box is the strip that lets visitors find things. Each control can be hidden independently, because a library of five files rarely needs all three.

The controls

Styles

Document Box

The Document Box tab styles each individual file card. It is the longest tab in the library editor, because it covers what the card shows, which buttons it carries, and how all of it looks in both normal and hover states.

Visibility options

Download button

View button

Card styles

Colors are set twice, once for Normal and once for Hover, so a card can respond to the pointer.

Library Container

The Library Container tab sets how many cards sit side by side, the space between them, and the frame around the whole library.

The grid

The frame

What Visitors See

On the front end the library renders as a header, then the toolbar strip, then a grid of cards. This page is what to expect once the shortcode is on a page.

What a visitor can do

• Type in the search box to filter by title, author or tag.
• Narrow the list to one file type with the type filter.
• Re-order by name, date or size.
• Click View to read a document in a popup, or Download to save it.

Filtering, sorting and searching all happen in the browser, so the grid responds as the visitor types rather than reloading the page.

How to tell it worked

Load the page as a visitor. You should see your header text, the toolbar strip with the controls you left switched on, and one card per file with the title, size and date you entered. Typing three letters of a title should narrow the grid immediately.

Reusing files across libraries

Libraries are independent collections, so the same file can appear in as many as you like, with a different title and description in each. Nothing is moved or copied when you add a file to a second library.

Leads Dashboard

Every submission the email gate collects lands in one table you can search, filter by document and date, export as CSV, and delete in bulk.

Find it at: the View Leads button in a document’s Download Stats panel, which opens the Download Leads screen already filtered to that document. Back To Doc List returns you to the document list.

The table

Each submission is one row.

Finding a lead

When a filter or search is active, a link appears to clear it and return to the full list.

Exporting and deleting

Where the numbers come from

A document’s Total Leads figure counts the rows in this table for that document, and Total Downloads counts every download of the file, gated or not. The two differ whenever the gate was switched on part-way through a document’s life.

Shortcode Reference

Two shortcodes cover everything the plugin renders. Both work anywhere a shortcode does, and [doc] accepts attributes that override a document’s saved settings for one placement only.

The two shortcodes

Click either shortcode in the admin to copy it to your clipboard.

Attributes for [doc]

id is required. Everything else is optional and overrides what the document has saved, for that one placement only. This is how you put the same document on two pages with different download labels.

Booleans accept yes, true or 1 for on, and no, false or 0 for off.

[doc id="7" download="yes" download_label="Get the 2026 report" download_behavior="download"]

Attributes for [document_library]

Calling a shortcode from PHP

<?php echo do_shortcode( '[doc id="7"]' ); ?>
<?php echo do_shortcode( '[document_library id="12"]' ); ?>

REST routes

The plugin registers five routes under the docembedder/v1 namespace. They exist for the plugin’s own front end and editor, and are listed here so you know what the traffic in your logs is.

Blocks & Page Builders

Document Embedder registers two blocks and two shortcodes, which between them cover the block editor, the Classic Editor, widgets and every page builder that accepts a shortcode.

The blocks

Page builders

Every builder below accepts a shortcode in a shortcode, text or HTML element. Paste [doc id="7"] or [document_library id="12"] into it and all of the saved settings travel with it.

• Elementor
• Divi
• Bricks
• WPBakery
• Beaver Builder
• Oxygen
• Breakdance

The document editor carries a Page Builder Support panel in its sidebar as a reminder, with the shortcode sitting right above it.

The Classic Editor and widgets

Paste the shortcode straight into the Classic Editor’s text area, or into a Text or Custom HTML widget. Nothing else is needed: the shortcode renders the same viewer everywhere.

Which one to reach for