PlugIndex

Directory / plugin

Rapls PDF Image Creator – PDF Thumbnails & Featured Images

v1.4.47 · by rapls

Turns PDFs into images. Refuses to save a blank thumbnail, works around a Ghostscript fault that makes one, and tells you what to ask your host.

View on WordPress.orgHomepage

About this plugin

Rapls PDF Image Creator automatically generates thumbnail images when you upload PDF files to your WordPress Media Library. The plugin uses ImageMagick (Imagick PHP extension) to convert a page of a PDF into an image — the first, unless you choose another for the whole site.

👉 Setup guide & troubleshooting: How to fix CMYK black thumbnails and PDF/X issues

Why this one

On a server with an older Ghostscript, a PDF page can come back completely white — and Ghostscript does not report it as an error. Anything that hands the page over and stores whatever comes back saves that white image, including WordPress’s own PDF preview. It looks like a thumbnail. It looks like the job worked.

Measured on a live shared host running Ghostscript 9.27, in a single upload: the built-in preview came back with a standard deviation of 0, one flat colour across every pixel. This plugin’s thumbnail of the same page, in the same request, came back at 0.31.

  • It looks at what came back. A page that renders as flat white is refused, not stored. WordPress shows its PDF icon and the Status tab says why, which is more use than a white square
  • It works around the cause. Ghostscript 9.27 and earlier fail on an image inside a transparency group — the kind of file PowerPoint and Illustrator produce. Retried with transparency switched off, the same page went from 11,018 bytes of white to 624,109 bytes of picture. Only ever as a retry: a page that rendered the first time is never touched
  • Every check is a measurement. Whether this server can read a PDF, render CMYK, or select a page other than the first is answered by doing it, not by reading a version number. On ImageMagick 6 the Status tab names the Ghostscript device your ImageMagick uses for CMYK PDFs
  • It tells you what to ask your host. “No PDF support”, “the page is too large”, “the uploads folder is not writable” and “the file is missing” are four problems with four different answers, and they no longer look the same
  • Real colour management, without the weight. CMYK is converted through ICC profiles rather than the arithmetic shortcut that turns greens fluorescent. The bundled sRGB profile is 3 KB, not the 64 KB kind that ends up embedded in every registered size
  • Nothing starts a process. No exec(), no shell. It works on locked-down shared hosting

Key Features

  • Automatic Generation – Thumbnails are created instantly when PDFs are uploaded
  • Featured Image Support – Generated thumbnails are automatically set as the PDF’s featured image
  • Multiple Sizes – Images are generated in all registered WordPress image sizes
  • Media Library Integration – Display thumbnails instead of default PDF icons
  • Editor Integration – Insert PDF links with thumbnail images into your posts
  • Bulk Generation – Generate thumbnails for all existing PDFs at once
  • Flexible Output – Choose from JPEG, PNG, or WebP formats

How It Works

  1. Upload a PDF file to the Media Library
  2. The plugin automatically converts the first page (or the one you choose) to an image
  3. The image is registered as the PDF’s featured image
  4. Use shortcodes or template functions to display the thumbnail

Generated Files

When you upload my-document.pdf, the plugin creates:

  • my-document-pdf-thumbnail.jpg (Full size cover image)
  • my-document-pdf-thumbnail-1024×768.jpg (Large)
  • my-document-pdf-thumbnail-300×225.jpg (Medium)
  • my-document-pdf-thumbnail-150×150.jpg (Thumbnail)
  • Additional sizes based on your theme settings

A thumbnail made again (“Regenerate Thumbnail”, or Bulk Generate with “Include PDFs that already have thumbnails (regenerate)”) gets a new name with a suffix, such as my-document-pdf-thumbnail-6512a3f0.jpg, so browsers do not keep showing the old image. The old image is deleted, unless a post’s content or excerpt or a widget shows it — by its address, or by its ID in an image or gallery block or a [gallery] shortcode — or a post uses it as its featured image; then it is kept as an ordinary image, and the screen that regenerated it says so, since that post still shows the old picture. A post in the trash counts, as it can be restored; revisions and drafts saved automatically do not. One a translated copy of the PDF shares is kept as that copy’s thumbnail. Block, Text, Custom HTML, Image and Gallery widgets are checked too; other settings that name an image are not. The extension follows the output format you choose.

Shortcodes

  • [rapls_pdf_thumbnail id="123"] – Display thumbnail image
  • [rapls_pdf_thumbnail_url id="123"] – Output thumbnail URL
  • [rapls_pdf_clickable_thumbnail id="123"] – Thumbnail linked to PDF
  • [rapls_pdf_download_link id="123"] – Download link with thumbnail

The thumbnail, clickable thumbnail and download link shortcodes take a class attribute, which can hold several classes separated by spaces: [rapls_pdf_thumbnail id="123" class="alignleft shadow"].

The shortcodes take a PDF’s ID. Up to 1.4.20 they also took any post’s ID and showed its featured image; a site with pages written that way can have it back with add_filter( 'rapls_pdf_image_creator_shortcode_any_post', '__return_true' );. A post is then shown only to a reader who may see it.

Template Functions

  • rapls_pic_get_thumbnail_url( $pdf_id, $size ) – Get thumbnail URL
  • rapls_pic_get_thumbnail_id( $pdf_id ) – Get thumbnail attachment ID
  • rapls_pic_get_thumbnail_image( $pdf_id, $size, $attr ) – Get thumbnail HTML
  • rapls_pic_has_thumbnail( $pdf_id ) – Check if PDF has thumbnail
  • rapls_pic_generate_thumbnail( $pdf_id, $force ) – Generate thumbnail

Requirements

  • WordPress 5.0 or higher
  • PHP 7.4 or higher
  • ImageMagick with Imagick PHP extension and PDF support

Most shared hosting providers have ImageMagick available. Check the Status tab in plugin settings to verify your server meets the requirements.

Will it work on my server?

PDF thumbnails depend on ImageMagick being able to read PDFs, and not every host allows that. Rapls PDF Image Creator checks by actually rendering a small test PDF, not by reading a configuration value, and tells you on the Status tab whether PDF rendering works on your server and, if not, what to ask your host for. Site Health flags it too when it doesn’t.

Optional add-on

Everything described above is free and stays free; nothing in this plugin is limited to make room for anything else. A separate, paid add-on, Rapls PDF Image Creator Pro, adds: cropping (white margins trimmed, the top of the page kept, or a fixed shape), a page and a crop for each PDF on its own edit screen, a background queue, replacing a PDF in place with the previous file kept, and rendering with Ghostscript directly where ImageMagick cannot read PDFs. That last one needs a host that lets PHP start programs (exec or proc_open) and has Ghostscript installed; this plugin cannot do it itself, because plugins in the WordPress.org directory may not start other programs. The plugin links to the add-on in five places only: its row on the Plugins screen, a card at the bottom of its Settings tab, the Status tab (as one of three options when this server cannot render PDFs, or a small box when it can), and under the page-number field after you change it, until you dismiss it. The filter rapls_pdf_image_creator_show_upsell, returning false, removes all of them.

Using Template Functions

Display a PDF thumbnail in your theme:

$pdf_id = 123;
if ( rapls_pic_has_thumbnail( $pdf_id ) ) {
    echo rapls_pic_get_thumbnail_image( $pdf_id, 'medium' );
}

Link thumbnail to PDF file:

$pdf_id = 123;
if ( $thumbnail_id = get_post_thumbnail_id( $pdf_id ) ) {
    echo '<a href="' . esc_url( wp_get_attachment_url( $pdf_id ) ) . '" target="_blank">';
    echo wp_get_attachment_image( $thumbnail_id, 'medium' );
    echo '</a>';
}

Display All PDFs Attached to a Post

$pdfs = get_posts( array(
    'post_type'      => 'attachment',
    'post_mime_type' => 'application/pdf',
    'post_parent'    => get_the_ID(),
    'posts_per_page' => -1,
) );

foreach ( $pdfs as $pdf ) {
    if ( rapls_pic_has_thumbnail( $pdf->ID ) ) {
        printf(
            '<a href="%s">%s</a>',
            esc_url( wp_get_attachment_url( $pdf->ID ) ),
            rapls_pic_get_thumbnail_image( $pdf->ID, 'thumbnail' )
        );
    }
}

Available Filter Hooks

  • rapls_pdf_image_creator_thumbnail_page – PDF page to use (default: 0)
  • rapls_pdf_image_creator_thumbnail_max_width – Maximum width
  • rapls_pdf_image_creator_thumbnail_max_height – Maximum height
  • rapls_pdf_image_creator_thumbnail_resolution – Rendering resolution in DPI (default: 150)
  • rapls_pdf_image_creator_max_render_pixels – Most pixels the chosen page is drawn at before resizing (default: 40000000 — a little above an A4 page at 600 DPI). A larger page is drawn at a lower resolution instead. The size is read from the PDF’s own page boxes, so this costs nothing for an ordinary PDF; a quick extra Ghostscript run measures the page only when the boxes cannot say, or say a page in the document may be over the limit
  • rapls_pdf_image_creator_thumbnail_quality – Image quality, 1-100 (the setting itself starts at 10)
  • rapls_pdf_image_creator_thumbnail_format – Output format
  • rapls_pdf_image_creator_thumbnail_bgcolor – Background color
  • rapls_pdf_image_creator_thumbnail_image_attributes – Image tag attributes
  • rapls_pdf_image_creator_custom_insert_html – Custom insert HTML
  • rapls_pdf_image_creator_hide_thumbnails_in_library – Hide in Media Library
  • rapls_pdf_image_creator_policy_paths – ImageMagick policy.xml paths to search when diagnosing blocked PDF support
  • rapls_pdf_image_creator_delegate_paths – ImageMagick delegates.xml paths to search when diagnosing which Ghostscript device CMYK PDFs are drawn with
  • rapls_pdf_image_creator_imagick_result – The conversion’s result, before it is returned; anything but a result object is ignored
  • rapls_pdf_image_creator_refuse_blank_page – Return false to keep a page that comes out all white instead of refusing it (default: true). Its second argument is the conversion’s options
  • rapls_pdf_image_creator_ghostscript_options – Ghostscript switches for the blank-page retry (default: -dNOTRANSPARENCY); switches that loosen its sandbox, point at files or change what is drawn are left out
  • rapls_pdf_image_creator_before_resize – The page as drawn, before it is resized; return it, changed or not
  • rapls_pdf_image_creator_engines – The conversion engines to choose from, in order; an entry that is not an engine is left out
  • rapls_pdf_image_creator_show_review_prompt – Return false to never show the request for a review
  • rapls_pdf_image_creator_pdfs_in_every_image_picker – Return true (exactly true: 1 or “1” is not taken) to offer PDFs with a thumbnail in every media picker that asks for images, as up to 1.4.20 (default: false, WordPress’s own pickers only). Its second argument is the media query; the block editor asks it once more with an empty array for its pickers
  • rapls_pdf_image_creator_shortcode_any_post – Return true (exactly true) for the shortcodes to take any post’s ID and show its featured image, as up to 1.4.20 (default: false, a PDF’s ID only)

Color Conversion Filters

  • rapls_pdf_image_creator_color_conversion – auto (default), icc or naive. naive restores the pre-1.1.0 colors
  • rapls_pdf_image_creator_icc_paths – Array of absolute paths to search, per profile type (srgb / cmyk)
  • rapls_pdf_image_creator_rendering_intent – An Imagick::RENDERINGINTENT_* value (default: relative colorimetric)
  • rapls_pdf_image_creator_flatten_background – Background transparency is flattened onto (default: the configured background, or white for JPEG)

Pointing the plugin at a specific pair of profiles:

add_filter( 'rapls_pdf_image_creator_icc_paths', function( $paths, $type ) {
    if ( 'cmyk' === $type ) {
        return array( '/srv/icc/JapanColor2011Coated.icc' );
    }
    return $paths;
}, 10, 2 );

Available Action Hooks

  • rapls_pdf_image_creator_before_generate – Before thumbnail generation
  • rapls_pdf_image_creator_after_generate – After successful generation
  • rapls_pdf_image_creator_generation_failed – When generation fails

Bundled third-party assets

sRGB2014.icc

An ICC colour profile from the International Color Consortium’s profile
registry (https://www.color.org/srgbprofiles.xalter), used as the destination
profile when converting CMYK PDF pages to sRGB, and attached to the generated
image.

Licence, from https://registry.color.org/profile-library/ :

“This profile is made available by the International Color Consortium, and may
be copied, distributed, embedded, made, used, and sold without restriction.
Altered versions of this profile shall have the original identification and
copyright information removed and shall not be misrepresented as the original
profile.”

Shipped unaltered. Compatible with GPL-2.0-or-later.

No other profile is bundled. CMYK profiles are read from the host when one is
present and are never redistributed.

Plugin tags