JPKCom DB
View on GitHub (opens in a new tab)

JPKCom Gutenberg Image Block Alt-Attribute — Guide & Tips

Dynamically and SEO-friendly update the alt text of Gutenberg image blocks in WordPress — installation and practical notes for the JPKCom plugin.

JPKCom Gutenberg Image Block Alt-Attribute provides SEO-friendly, dynamic updates for the alt text of Gutenberg image blocks. The plugin works without a settings page — once activated, it takes effect automatically.

Guide

Requirements

  • WordPress 7.0 or newer (tested up to WordPress 7.1)
  • PHP 8.3 or newer

Installation

  1. In your admin panel, go to Plugins → Add New and click Upload Plugin.
  2. Choose the plugin's ZIP file and click Install Now.
  3. Click Activate — the plugin is ready to use right away.

There is no settings page. Once the plugin is active, the alt attributes of image blocks are updated dynamically.

Finding the gaps: the Abilities API

Since version 1.1.0 the plugin registers one read-only ability, jpkcom-gutenberg-img-alt/list-images-missing-alt. The Abilities API is a WordPress core registry of machine-readable capabilities — an AI assistant, an MCP client or REST automation can use it to ask which images this plugin has nothing to inject for.

That is a more useful question than "which images have no alt text": because the plugin takes the alt text from the attachment at render time, filling it in once fixes every core/image block that references that attachment. No post has to be re-saved and no block markup has to be touched. What the mechanism cannot do is invent an alt text the attachment does not have — and that residual gap is exactly what the ability reports.

What comes back is more than a plain "empty": the ability distinguishes four cases and names each one through a reason field instead of lumping them together. Two of them look set in the media library but do not work:

  • zero — a single 0. PHP treats it as empty, so the injection skips it.
  • whitespace_only — alt text consisting only of spaces is skipped as well.

The other two are genuinely empty, but not the same thing:

  • empty — a value is stored, and it is blank.
  • no_row — this image never had alt text saved at all.

That way it is clear whether the field was never filled, was emptied, or holds something that does not work.

The ability requires the upload_files capability — deliberately stricter than the sibling JPKCom plugins, which publish content the site already shows to visitors. This one enumerates the media library, so subscribers are excluded. To switch it off entirely, in wp-config.php:

define( 'JPKCOM_GUTENBERG_IMG_ALT_ABILITIES', false );

The filter jpkcom_gutenberg_img_alt_ability_capability narrows it further; jpkcom_gutenberg_img_alt_ability_meta controls how the ability is exposed (REST route, MCP visibility, annotations).

Tips & Tricks

  • Meaningful alt text helps SEO: Good alt attributes benefit both search engines and screen readers. The plugin keeps the alt text in the core/image block dynamically up to date.
  • Activate and forget: As there is no configuration, nothing needs to be set up after activation.
  • $ characters in alt text — updating to 1.0.8 recommended: If an alt text contained the sequences $1, ${1}, $2 or \1, it corrupted the rendered <img> tag up to version 1.0.7. Those sequences are backreferences inside the replacement, so ordinary editorial text — a price, a version number — was substituted with part of the image tag. In the $2 case the tag was closed early and the remainder leaked onto the page as visible text. Found and fixed by @yoldaolmak (opens in a new tab) (Kemal Kaya).
  • Whitespace-only alt text: Since 1.0.8 an alt text consisting only of whitespace no longer overwrites the alt attribute already present in the markup.
  • Translatable since 1.1.0: Translatable strings did exist in the updater as far back as 1.0.2, but without a Text Domain header they were neither extractable nor loadable. Version 1.1.0 added Text Domain and Domain Path headers plus a translation template; most of the texts come from the new ability. No finished translation files ship with it yet.
  • Reproducible updates: Since version 1.0.2 the plugin uses secure self-hosted updates via GitHub with SHA256 checksums and runs with declare(strict_types=1).

Further reading