# 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.

Source: https://www.jpkc.com/db/en/guides/jpkcom-gutenberg-img-alt/

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 **five** 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.

Two more 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.

The fifth case was added in 1.2.0. The media library never produces it; it only arises when code writes `_wp_attachment_image_alt` directly:

- `not_text` — a serialised array, object or other non-text value is stored. Up to 1.1.0 the plugin injected an array as the literal word `Array`, together with a PHP warning; since 1.2.0 it injects only text and otherwise leaves the block unchanged.

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`:

```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](https://github.com/yoldaolmak) (Kemal Kaya).
- **More robust since 1.2.0:** The plugin now sets the alt text with WordPress' HTML Tag Processor (`WP_HTML_Tag_Processor`) instead of a regular expression. The expression only handled the exact markup core produces and failed silently on anything else — it could, for example, overwrite `data-alt` instead of `alt`. If an image block's `<img>` has no `alt` attribute at all, it now receives one; previously only an existing attribute could be rewritten. And an alt text that literally contains `&amp;` now appears exactly as you typed it.
- **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

- Source code on GitHub: <https://github.com/JPKCom/jpkcom-gutenberg-img-alt>
- API documentation (PHPDoc): <https://jpkcom.github.io/jpkcom-gutenberg-img-alt/docs/>
- [This project's changelog](https://www.jpkc.com/db/en/changelog/jpkcom-gutenberg-img-alt/)