Rapls PDF Image Creator – PDF Thumbnails & Featured Images

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 the first page of a PDF into an image.

👉 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. The Status tab names the Ghostscript device your ImageMagick uses
• 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 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.jpg (Full size cover image)
• my-document-pdf-1024×768.jpg (Large)
• my-document-pdf-300×225.jpg (Medium)
• my-document-pdf-150×150.jpg (Thumbnail)
• Additional sizes based on your theme settings

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

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.

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_thumbnail_quality – Image quality (1-100)
• 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

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.