Documentation

Getting Started Guide

Everything you need to know to start sharing your PDFs professionally. Complete documentation for WordPress, Drupal and React / Next.js.

Getting Started

Install and configure the plugin in minutes

Install the Plugin

Via WordPress Admin:

Go to Plugins > Add New
Search for "PDF Embed SEO Optimize"
Click Install, then Activate

Or via WP-CLI:

wp plugin install pdf-embed-seo-optimize --activate

Upload Your First PDF

Go to PDF Documents > Add New
Enter a title for your PDF
Click "Upload PDF" and select your file
Add a description (optional but recommended for SEO)
Click "Publish" to make it live

Configure Display Options

Choose viewer type: In-Page or Standalone
Toggle Download and Print permissions
Set viewer height (default: 800px)
Add password protection (Pro feature)

View Your PDF

Click "View PDF" to see the SEO-optimized page
Check /pdf/ to see all your documents
Share the URL - it's search engine ready!

Install the Module

Manual Installation:

Download and extract to modules/contrib/pdf_embed_seo/
Enable via Drush: drush en pdf_embed_seo
Or enable via UI: Admin > Extend > PDF Embed & SEO Optimize

For Premium features:

drush en pdf_embed_seo_premium

Requirements

Drupal: 10 or 11
PHP: 8.1 or higher
Dependencies: Node, File, Taxonomy, Path, Path Alias modules
Optional: ImageMagick or Ghostscript (for automatic thumbnail generation)

Upload Your First PDF

Go to Content > Add content > PDF Document
Enter a title for your PDF
Upload your PDF file
Add a description for SEO
Save to publish

Configure Module Settings

Go to Configuration > Content > PDF Embed & SEO
Set default viewer options and theme
Configure download/print permissions
Set archive page display style (grid/list)
Enable GDPR IP anonymization (IPv4: zeros last octet, IPv6: zeros last 80 bits)

View Your PDF

Visit /pdf to see the archive
Each PDF gets its own SEO-friendly URL at /pdf/{slug}
Schema.org markup is automatically added
XML Sitemap available at /pdf/sitemap.xml (Premium)

Install the Package

Via npm or yarn:

npm install @pdf-embed-seo/react

or with yarn:

yarn add @pdf-embed-seo/react

Import the Component

In your React component:

import { PdfViewer } from '@pdf-embed-seo/react';

Use the Component

Basic usage example:

<PdfViewer src="/documents/annual-report.pdf" title="Annual Report 2024" height="600px" allowDownload={true} allowPrint={true}
/>

Next.js App Router (Optional)

For Next.js with App Router, use dynamic import:

'use client';
import dynamic from 'next/dynamic';
const PdfViewer = dynamic( () => import('@pdf-embed-seo/react').then(mod => mod.PdfViewer), { ssr: false }
);

Configuration

Navigate to: PDF Documents > Settings Navigate to: Admin > Configuration > Content > PDF Embed & SEO

Setting	Default	Description
Allow Download by Default	Yes	New PDFs allow downloads
Allow Print by Default	Yes	New PDFs allow printing
Auto-generate Thumbnails	Yes	Create thumbnails from PDF
Viewer Theme	Light	Light or Dark theme
Viewer Height	800px	Default viewer height
Archive Posts per Page	12	PDFs per archive page

Automatic Google Sitemap

Help search engines find all your PDF documents automatically

Your PDF sitemap is available at:

yourdomain.com/pdf/sitemap.xml

The plugin automatically creates a special sitemap just for your PDFs. This helps Google and other search engines discover and index all your documents, making them easier for customers to find.

Good to know: You can submit this sitemap to Google Search Console to help your documents appear in search results faster.

Shortcodes & Blocks

Embed PDFs anywhere on your site

Quick Embed Steps

Get PDF ID

Find it in PDF Documents list

Add Shortcode

Use [pdf_viewer id="X"]

Customize Size

Add width/height attributes

Publish

Save and preview your page

[pdf_viewer]

Embed a single PDF viewer.

Attribute	Default	Description
id	Current post	PDF document ID
width	100%	Viewer width
height	800px	Viewer height

[pdf_viewer id="123" width="100%" height="600px"]

[pdf_viewer_sitemap]

Display a list of all PDFs.

Attribute	Default	Description
orderby	title	Sort: title, date, menu_order
order	ASC	Direction: ASC, DESC
limit	-1	Number of PDFs (-1 for all)

[pdf_viewer_sitemap orderby="date" order="DESC" limit="10"]

Gutenberg Block

In the block editor, click "+" to add a block
Search for "PDF Viewer"
Select the PDF document from the dropdown
Adjust width/height in block settings

Quick Embed Steps

Create PDF

Add PDF Document content

Place Block

Add PDF Viewer block

Configure

Select PDF and set options

Clear Cache

Run drush cr to apply

PDF Viewer Block

Add the PDF Viewer block to any page or layout.

Go to Structure > Block Layout
Click "Place block" in the desired region
Search for "PDF Viewer"
Configure the block settings and save

Twig Templates

Override templates in your theme for custom styling.

pdf-document.html.twig

Single PDF document page template

pdf-viewer.html.twig

PDF viewer component template

pdf-archive.html.twig

PDF archive listing template

Render in Twig

Embed a PDF viewer programmatically using a preprocess function:

// In mytheme.theme or custom module
$build = \Drupal::service('plugin.manager.block') ->createInstance('pdf_viewer_block', [ 'pdf_id' => $node->field_pdf->target_id, ])->build();
// Then in Twig template:
{{ pdf_viewer }}

Permissions

Configure at: Admin > People > Permissions

Permission	Description
administer pdf embed seo	Configure global module settings
view pdf document	View published PDFs (public)
create pdf document	Create new documents
edit own pdf document	Edit only own documents
view pdf analytics	Access analytics dashboard (Premium)
bypass pdf password	View protected PDFs without password (Premium)

Services

Available Drupal services for custom development:

pdf_embed_seo.thumbnail_generator
Generate thumbnail images from PDF first pages
pdf_embed_seo.analytics_tracker
Track and query view/download statistics (Premium)
pdf_embed_seo.progress_tracker
Save and retrieve reading progress (Premium)
pdf_embed_seo.schema_enhancer
Enhance Schema.org with GEO/AEO/LLM optimizations (Premium)
pdf_embed_seo.bulk_operations
Perform bulk import/update operations (Premium)

JavaScript Events

Listen for PDF viewer events in your custom JavaScript:

document.addEventListener('pdfLoaded', (e) => { console.log('Pages:', e.detail.numPages);
});
document.addEventListener('pageRendered', (e) => { console.log('Rendered:', e.detail.pageNumber);
});
document.addEventListener('pageChanged', (e) => { console.log('Page:', e.detail.pageNumber);
});
document.addEventListener('zoomChanged', (e) => { console.log('Zoom:', e.detail.scale);
});

URL Structure

Page	Path
Archive	/pdf
Single PDF	/pdf/{slug}
XML Sitemap (Premium)	/pdf/sitemap.xml
Admin List	/admin/content/pdf-documents
Settings	/admin/config/content/pdf-embed-seo
Analytics (Premium)	/admin/reports/pdf-analytics

Quick Start

Install Package

npm install @pdf-embed-seo/react

Import Component

import { PdfViewer }

Add Props

src, title, height, etc.

Render

Component renders PDF viewer

<PdfViewer />

Main component for embedding PDFs in React applications.

Prop	Type	Default	Description
src	string	—	PDF file URL (required)
title	string	—	Document title for accessibility
width	string	'100%'	Viewer width
height	string	'600px'	Viewer height
allowDownload	boolean	true	Show download button
allowPrint	boolean	true	Show print button
initialPage	number	1	Starting page number
initialZoom	string	'auto'	'auto', 'page-fit', 'page-width', or percentage
className	string	—	Custom CSS class

<PdfViewer src="/documents/report.pdf" title="Annual Report" height="700px" allowDownload={true} allowPrint={false}
/>

PDF AcroForms (Fillable Forms)

Interactive form fields in your PDF viewer

What are AcroForms?

AcroForms are interactive form fields embedded in PDF documents. When a PDF contains fillable fields (text inputs, checkboxes, radio buttons, dropdowns), the viewer automatically detects them and displays an interactive form toolbar.

This feature works with any PDF that contains standard AcroForm fields — no additional configuration is required. Simply upload your fillable PDF and the form toolbar appears automatically.

How It Works

Upload PDF

Upload a PDF with AcroForm fields

Auto-Detection

Viewer detects form fields automatically

Fill Fields

Users fill in text, checkboxes, and dropdowns

Download / Print

Download or print the filled PDF

Form Toolbar

When a PDF with form fields is loaded, a blue toolbar appears below the main viewer toolbar with these controls:

Button	Description
Form Fields Detected	Label indicating the PDF contains fillable form fields. Toolbar only appears when form fields are found.
Clear Form	Resets all form fields to their default empty state. Useful when users want to start over.
Download Filled PDF	Downloads the PDF with all filled-in form data embedded. Only shown when downloads are enabled for the document.

Supported Field Types

Text Fields

Single-line and multi-line text inputs for names, addresses, comments, etc.

Checkboxes

Toggle checkboxes for yes/no options, agreements, and multi-select choices.

Radio Buttons

Single-select option groups where only one choice can be selected.

Dropdown Menus

Select menus with predefined options for structured data entry.

WordPress

AcroForms work automatically with any PDF uploaded via the PDF Documents admin. No shortcode changes needed — forms are detected on page load.

Drupal

Upload a fillable PDF via the PDF Document entity form. The viewer template includes the annotation layer and form toolbar out of the box.

React / Next.js

The PdfViewer component handles AcroForms automatically. Form fields render as interactive overlays when detected in the loaded PDF.

REST API Reference

Base URL: /wp-json/pdf-embed-seo/v1/ Base URL: /api/pdf-embed-seo/v1/

GET /documents

List all published PDF documents.

Parameter	Type	Description
page	int	Page number (default: 1)
per_page	int	Items per page (max 100)
search	string	Search term
orderby	string	date, title, modified, views

GET /documents/{id}

Get single PDF document details.

Returns: id, title, slug, url, description, thumbnail, file_size, page_count, view_count, dates

GET /documents/{id}/data

Get secure PDF URL for viewer (AJAX-based).

Returns: success, url (temporary secure URL), expires

POST /documents/{id}/view

Track a PDF view (increment view counter).

GET /settings

Get public plugin settings (viewer theme, height, permissions).

Premium Endpoints

Pro

GET /analytics Dashboard summary (total views, unique visitors, popular docs)
GET /analytics/documents Per-document analytics
GET /analytics/export Export data (CSV/JSON)
GET /documents/{id}/progress Get reading progress
POST /documents/{id}/progress Save reading progress (page, scroll, zoom)
POST /documents/{id}/verify-password Verify password for protected PDFs
POST /documents/{id}/download Track PDF download
POST /documents/{id}/expiring-link Generate expiring access link

Example Response

{ "id": 123, "title": "Annual Report 2024", "slug": "annual-report-2024", "url": "https://example.com/pdf/annual-report-2024/", "excerpt": "Company annual report...", "date": "2024-01-15T10:30:00+00:00", "views": 1542, "thumbnail": "https://example.com/wp-content/uploads/thumb.jpg"
}

WordPress Hooks Drupal Hooks

Extend and customize the plugin functionality

Actions

pdf_embed_seo_pdf_viewed Fired when PDF is viewed ($post_id, $count)
pdf_embed_seo_premium_init Premium features initialized
pdf_embed_seo_settings_saved Settings saved

Filters

pdf_embed_seo_schema_data Modify Schema.org data for a single PDF
pdf_embed_seo_archive_schema_data Modify Schema.org data for archive page
pdf_embed_seo_archive_query Modify archive page posts per page
pdf_embed_seo_sitemap_query_args Modify sitemap shortcode query args
pdf_embed_seo_archive_title Modify the archive page title
pdf_embed_seo_archive_description Modify the archive page description
pdf_embed_seo_viewer_options Modify PDF.js viewer options
pdf_embed_seo_allowed_types Modify allowed MIME types for upload
pdf_embed_seo_rest_document Modify REST API document response
pdf_embed_seo_rest_document_data Modify REST API document data
pdf_embed_seo_rest_settings Modify REST API settings response

Example: Add custom schema data

add_filter( 'pdf_embed_seo_schema_data', function( $schema, $post_id ) { $schema['author'] = [ '@type' => 'Person', 'name' => get_post_meta( $post_id, '_pdf_author', true ), ]; return $schema;
}, 10, 2 );

Alter Hooks

hook_pdf_embed_seo_document_data_alter Modify API document data before response
hook_pdf_embed_seo_schema_alter Customize Schema.org structured data
hook_pdf_embed_seo_viewer_options_alter Modify PDF.js viewer configuration
hook_pdf_embed_seo_api_settings_alter Modify REST API settings response
hook_pdf_embed_seo_verify_password_alter Override password verification logic (Premium)

Event & Entity Hooks

hook_pdf_embed_seo_view_tracked Triggered when a PDF view is tracked
hook_pdf_embed_seo_document_saved Triggered when a PDF document is saved
hook_pdf_document_insert Document created
hook_pdf_document_update Document updated
hook_pdf_document_delete Document deleted

Preprocessing Hooks

template_preprocess_pdf_document Preprocess single document variables
template_preprocess_pdf_viewer Preprocess viewer variables
template_preprocess_pdf_archive Preprocess archive listing variables
template_preprocess_pdf_archive_item Preprocess archive item variables

Example: Custom Schema

/** * Implements hook_pdf_embed_seo_schema_alter(). */
function mymodule_pdf_embed_seo_schema_alter(array &$schema, $document) { $schema['author'] = [ '@type' => 'Person', 'name' => $document->get('field_author')->value, ];
}

Example: View Tracking

/** * Implements hook_pdf_embed_seo_view_tracked(). */
function mymodule_pdf_embed_seo_view_tracked($document_id, $analytics_data) { \Drupal::logger('mymodule')->info('PDF @id viewed', ['@id' => $document_id]);
}

Event Callbacks

React props for handling PDF viewer events.

Prop	Parameters	Description
onLoad	(pdf: PDFDocument) => void	Called when PDF finishes loading
onError	(error: Error) => void	Called on loading or rendering error
onPageChange	(page: number) => void	Called when page changes
onZoomChange	(zoom: number) => void	Called when zoom level changes
onDownload	() => void	Called when download button clicked
onPrint	() => void	Called when print button clicked

Example: Analytics Tracking

import { PdfViewer } from '@pdf-embed-seo/react';
export default function TrackedDocument({ src, title }) { const handleLoad = (pdf) => { analytics.track('pdf_viewed', { title, pages: pdf.numPages }); }; const handlePageChange = (page) => { analytics.track('pdf_page_viewed', { page, title }); }; return ( <PdfViewer src={src} title={title} onLoad={handleLoad} onPageChange={handlePageChange} onError={(err) => console.error('PDF Error:', err)} /> );
}

Theming & Templates

Customize the look and feel

Copy Template Files

Navigate to wp-content/plugins/pdf-embed-seo-optimize/templates/
Copy the template file you want to customize
Paste it into your theme folder (e.g., wp-content/themes/your-theme/)

Available Template Files

single-pdf_document.php Controls single PDF page layout, viewer placement, and metadata display
archive-pdf_document.php Controls PDF archive/listing page with grid or list view
content-pdf_document.php Individual PDF card in archive listings

Customize with CSS

Add custom styles to your theme's style.css:

/* Custom PDF viewer styling */
.pdf-viewer-container { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}
/* PDF archive grid */
.pdf-archive-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 1.5rem;
}

Use Template Tags

Available template tags for your custom templates:

pdf_embed_seo_get_viewer() - Output the PDF viewer
pdf_embed_seo_get_thumbnail() - Get PDF thumbnail URL
pdf_embed_seo_get_download_url() - Get secure download URL
pdf_embed_seo_get_page_count() - Get PDF page count
pdf_embed_seo_get_view_count() - Get view count

Copy Twig Templates

Navigate to modules/pdf_embed_seo/templates/
Copy the .html.twig file you want to customize
Paste it into your theme's templates/ folder
Clear Drupal cache: drush cr

Available Twig Templates

pdf-document.html.twig Single PDF document page layout
pdf-viewer.html.twig PDF.js viewer component
pdf-archive.html.twig Archive listing page
pdf-archive-item.html.twig Individual archive item (grid card or list row)
pdf-password-form.html.twig Password protection form (Premium)

Template Variables

pdf-viewer.html.twig:

pdf_document - The PDF document entity
pdf_url - Secure URL to the PDF file
allow_download - Boolean for download permission
allow_print - Boolean for print permission
viewer_theme - 'light' or 'dark'

pdf-archive.html.twig:

documents - Array of PDF document entities
pager - Pagination render array
display_style - 'grid' or 'list'
archive_title - Page heading
content_alignment - Alignment setting

Add Custom Styles

Add styles to your theme's CSS or create a custom library:

/* In your-theme.libraries.yml */
pdf-custom: css: theme: css/pdf-custom.css: {}

Body CSS Classes

The module adds CSS classes to the body element for page-specific styling:

.page-pdf - Applied to all PDF-related pages
.page-pdf-document - Applied to single PDF document pages
.page-pdf-archive - Applied to PDF archive/listing pages

Example usage:

/* Hide sidebar on PDF pages */
body.page-pdf .sidebar { display: none;
}
/* Full-width viewer on document pages */
body.page-pdf-document .content-wrapper { max-width: 100%; padding: 0;
}

CSS Customization

Style the PDF viewer using CSS classes or the className prop.

CSS Class	Description
.pdf-viewer	Main container element
.pdf-viewer__toolbar	Top toolbar with controls
.pdf-viewer__canvas	PDF rendering canvas
.pdf-viewer__page	Individual page container
.pdf-viewer__loading	Loading spinner overlay

Custom Styling Example

/* styles.css */
.my-pdf-viewer { border-radius: 12px; overflow: hidden; box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
}
.my-pdf-viewer .pdf-viewer__toolbar { background: linear-gradient(to right, #3b82f6, #1d4ed8); color: white;
}
.my-pdf-viewer .pdf-viewer__canvas { background: #f8fafc;
}

// Component usage
<PdfViewer src="/document.pdf" className="my-pdf-viewer"
/>

CSS Variables

Override these CSS custom properties to customize colors globally:

:root { --pdf-viewer-primary: #3b82f6; --pdf-viewer-background: #ffffff; --pdf-viewer-toolbar-bg: #f1f5f9; --pdf-viewer-border-color: #e2e8f0; --pdf-viewer-text-color: #1e293b;
}

Developer Documentation

For Developers

Extend and integrate PDF Embed with hooks, REST API, and webhooks

Premium Feature Classes

Feature	Class	Description
Analytics Dashboard	`Premium_Analytics`	Dashboard widget, view tracking, unique visitors, time spent
Password Protection	`Premium_Password`	Per-PDF password with hashed storage, brute-force protection
Detailed View Tracking	`Premium_Tracking`	IP, user agent, referrer tracking
Reading Progress	`Premium_Progress`	Save/resume reading position, page, scroll, zoom
XML Sitemap	`Premium_Sitemap`	Dedicated sitemap at /pdf/sitemap.xml with XSL styling
PDF Categories & Tags	`Premium_Taxonomies`	Hierarchical categories, flat tags, archive filtering
CSV/JSON Export	`Premium_Export`	Export analytics data in CSV or JSON format
Role-Based Access	`Premium_Roles`	Require login, limit by user role
Bulk Import	`Premium_Bulk`	Import multiple PDFs via CSV/ZIP with category assignment
Full REST API	`Premium_API`	Complete API access for integrations
White-Label Options	`Premium_WhiteLabel`	Remove branding, customize viewer appearance

WordPress Hooks (Extended)

pdf_embed_seo_pdf_viewed action

Fires after a PDF is viewed with post ID and view count

add_action( 'pdf_embed_seo_pdf_viewed', function( $post_id, $count ) { // Your code here
}, 10, 2 );

pdf_embed_seo_schema_data filter

Modify Schema.org DigitalDocument data for a single PDF

add_filter( 'pdf_embed_seo_schema_data', function( $schema, $post_id ) { $schema['author'] = [ '@type' => 'Person', 'name' => get_post_meta( $post_id, '_author', true ), ]; return $schema;
}, 10, 2 );

pdf_embed_seo_viewer_options filter

Modify PDF.js viewer options

add_filter( 'pdf_embed_seo_viewer_options', function( $options, $post_id ) { $options['defaultZoom'] = 'page-fit'; return $options;
}, 10, 2 );

pdf_embed_seo_rest_document filter

Modify REST API document response

add_filter( 'pdf_embed_seo_rest_document', function( $data, $post, $detailed ) { $data['custom_field'] = get_post_meta( $post->ID, '_custom', true ); return $data;
}, 10, 3 );

REST API Reference /wp-json/pdf-embed-seo/v1/

Method	Endpoint	Description	Tier
GET	`/documents`	List all published PDF documents
GET	`/documents/{id}`	Get single PDF document details
GET	`/documents/{id}/data`	Get PDF file URL securely (for viewer)
GET	`/analytics`	Get analytics overview (requires admin)	Premium
POST	`/documents/{id}/expiring-link`	Generate expiring access link	Premium
POST	`/bulk/import`	Bulk import PDFs via CSV/ZIP	Premium

JavaScript Events

Listen for viewer events to build custom integrations.

pdfLoaded

PDF document loaded successfully

pageRendered

A page has been rendered

pageChanged

User navigated to a different page

zoomChanged

Zoom level was changed

Premium Features

Pro

Advanced functionality for Pro users

Analytics Dashboard

Total views and unique visitors
Popular documents ranking
Time period filters (7d, 30d, 90d, 12m)
CSV/JSON export

Password Protection

Per-PDF password settings
Secure password hashing
Brute-force protection
AJAX-based verification

Reading Progress

Auto-save reading position
Resume from last page
Track scroll and zoom
Works for all users

XML Sitemap

Available at /pdf/sitemap.xml
XSL-styled browser view
Auto-updates on changes
Submit to Google Search Console

Download Tracking

Track downloads separately from views
Separate download counter per PDF
User attribution for logged-in users
REST API endpoint for tracking

Expiring Access Links

Generate time-limited URLs
Configurable expiration (5min-30 days)
Max usage limits per link
Secure token-based access

View All Pro Features Developer Docs