Rapls PDF Image Creator – PDF Thumbnails & Featured Images

A full guide with setup instructions, the fix for the infamous “black thumbnail” problem (CMYK / PDF/X), and real-world usage tips:

• Rapls PDF Image Creator — Setup & Troubleshooting Guide
• Source code on GitHub
• Developer’s blog — Rapls Works

You need ImageMagick with the Imagick PHP extension and PDF support. Most shared hosting providers have this available. Contact your hosting provider if you need to enable it.

Go to Settings > Rapls PDF Image Creator > Status tab. The plugin will show whether ImageMagick is available and properly configured.

For detailed troubleshooting including common server setup issues, see the setup guide .

Check Settings > Rapls PDF Image Creator > Status. If the CMYK PDF Rendering row says “Broken on this server (tested)”, that is the cause. If it says the test could not be run, it may be.

ImageMagick 6 can render a PDF it judges to be CMYK through Ghostscript’s bmpsep8 device, which writes a separation BMP that ImageMagick’s own BMP reader cannot decode. Depending on the exact ImageMagick and Ghostscript versions, the read either fails outright or returns an empty raster — which becomes a blank white thumbnail. ImageMagick 7 uses a different device and is unaffected.

Not every ImageMagick 6 build is affected: on Xserver’s 6.9.13-25 a CMYK page renders correctly. Since 1.3.2 the Status tab renders a test page and reports what this server actually does, rather than warning on the version number.

The plugin cannot work around this, because ImageMagick picks the device from the PDF’s own content and no Imagick API call overrides it. Ask your hosting provider to upgrade to ImageMagick 7, or to change the ps:cmyk delegate in delegates.xml from bmpsep8 to pamcmyk32 . The second has no effect where ImageMagick calls Ghostscript as a library ( gslib in the output of convert -list configure ); then only the upgrade helps.

RGB PDFs are not affected, which is why only some of your PDFs fail.

If the PDF uses CMYK colours and no ICC profile is available on your server, the plugin falls back to a simple arithmetic conversion, which exaggerates greens and blues. Check Settings > Rapls PDF Image Creator > Status to see whether ICC colour management is active. Installing a CMYK profile on the server, or pointing the rapls_pdf_image_creator_icc_paths filter at one, restores accurate colours.

Thumbnails are not regenerated automatically, because regenerating every PDF on a large site during an update is not something a plugin should decide to do. Go to Settings > Rapls PDF Image Creator > Bulk Generate and regenerate them.

If you would rather keep the previous colours, pin the old behaviour:

add_filter( 'rapls_pdf_image_creator_color_conversion', function() { return 'naive'; } );

Yes. Go to Settings > Rapls PDF Image Creator > Bulk Generate tab to scan and generate thumbnails for all existing PDFs.

For one PDF, use the “Generate Thumbnail” or “Regenerate Thumbnail” link under it in the Media Library. The link is in the list view only; in the grid view, switch to the list view first.

Those two settings only scale the rendered page down . They never enlarge it. The size the page is rendered at comes from Rendering Resolution instead, which was fixed at 150 DPI before version 1.2.0 — an A4 page at 150 DPI is about 1240×1754 pixels, and no maximum above that could produce anything bigger.

Raise Rendering Resolution (Settings > Rapls PDF Image Creator > Image Settings) and the rendered page grows with it; the maximum dimensions then cap the result as before. Bear in mind that memory use during generation grows with the square of the resolution, so raise it in steps if your server is small.

Go to Tools > Site Health. The “PDF thumbnail generation” test says whether this server can render PDFs, and if not, what to ask your hosting provider for. The same report is on the Status tab of the plugin’s settings page, and Site Health > Info has a Rapls PDF Image Creator section you can copy into a support request.

There are two different server problems, and they need different requests:

• The Imagick PHP extension is not installed. Ask your host to install and enable it. It is the PHP binding for ImageMagick.
• ImageMagick is installed but its security policy forbids reading PDFs. Many hosts ship a policy.xml that denies the PDF coder, a precaution left over from a 2018 Ghostscript vulnerability. Ask your host to give the PDF coder read rights. The plugin shows the path of the file responsible.

The plugin tells these apart for you, so you do not have to guess which request to make.

JPEG, PNG, and WebP. Choose one under Image Settings on the Settings tab. WebP needs WordPress 5.8 or later and an ImageMagick that can write it; the setting says so when this server cannot.

By default, yes. To keep generated images as regular attachments, enable “Keep Images on Uninstall” in Display Settings before uninstalling.

Even with that setting off, uninstalling keeps a generated image that a post uses as its featured image, or that a post’s content or excerpt or a widget shows (its address, or its ID or the PDF’s in an image or gallery block, a [gallery] shortcode or this plugin’s own shortcodes), and makes it an ordinary image. A post in the trash counts, as it can be restored; revisions and drafts saved automatically do not. It also keeps one that a translated copy of the PDF shares. Featured images, post content and excerpts, and block, Text, Custom HTML, Image and Gallery widgets are checked — in them, also any number where an ID could stand, as page builders keep an image by ID: an image used in a theme or page-builder setting, or anywhere else, is not found, so turn on “Keep Images on Uninstall” if you use them there. A post whose featured image was a PDF is given that PDF’s image instead, with the setting on or off, so it looks as it did. If any of this cannot be checked, no image is deleted. On a very large site, reading every post can take longer than the server allows; if uninstalling stops there, no image has been deleted.

With “Hide Generated Images” on, the PDF’s thumbnail is deleted with it, unless a post or a widget shows it, a post uses it as its featured image, or a translated copy of the PDF shares it. One a post or widget shows is kept as an ordinary image, attached where the PDF was; one a translated copy shares stays that copy’s thumbnail. With the setting off, every thumbnail is kept as an ordinary image, except one a translated copy shares, which stays that copy’s thumbnail.

Since 1.4.46, PDFs with a thumbnail are offered only in WordPress’s own image pickers: the image, gallery and featured image blocks, and the classic editor’s featured image. An image picker of another plugin may take only images, and a PDF handed to it broke there. If yours takes them, as every picker did up to 1.4.20, turn it back on: add_filter( 'rapls_pdf_image_creator_pdfs_in_every_image_picker', '__return_true' ); .

Yes. Use the rapls_pdf_image_creator_thumbnail_page filter:

add_filter( 'rapls_pdf_image_creator_thumbnail_page', function( $page, $pdf_id ) { return 1; // Use second page (0-indexed) }, 10, 2 );

Without code, you can set the page for the whole site in Settings > Rapls PDF Image Creator > Page Number (0 is the first page).

In Settings > Rapls PDF Image Creator, under Insert Settings, choose Thumbnail Image, Title (text link only) or Custom HTML. A custom template can use %PDF_URL% , %THUMBNAIL_URL% , %TITLE% , %ID% and %ATTACHMENT_URL% . These settings apply to “Insert into post” in the classic editor’s Add Media window; the block editor does not use them.

The plugin itself never runs Ghostscript. ImageMagick does, though: it passes PDFs to Ghostscript to read them, so ImageMagick’s PDF support only works if Ghostscript is installed on the server. You don’t have to check this by hand. The Status tab (Settings > Rapls PDF Image Creator > Status) tells you whether PDFs can be rendered on your server.

It is not a fault in this plugin, but PDFs reach Ghostscript through it. CVE-2026-39919 is a buffer overflow in Ghostscript before 10.08.0, set off by a crafted PDF. This plugin never runs Ghostscript itself; ImageMagick does, to draw a PDF, and WordPress’s own PDF preview takes the same path, so turning the plugin off does not take a site out of it. The fix is on the server: ask your hosting provider whether its Ghostscript is 10.08.0 or later, or a distribution package that includes the fix. The version number alone cannot tell, because distributions add the fix to older versions, so the plugin does not check it; where this server renders PDFs, the Status tab and Site Health say what to ask. Until the host confirms it, denying the PDF coder in ImageMagick’s policy.xml keeps PDFs away from Ghostscript, and stops both this plugin’s thumbnails and WordPress’s PDF previews. As of October 17, 2026, no attack using it had been reported, and whether one succeeds depends on the server.

Two causes of black thumbnails have been fixed: PDF/X-1:2001 files (1.0.9), and transparent areas (1.1.0), which are now flattened onto the background colour you cho