JPKCom DB
Auf GitHub ansehen (öffnet in neuem Tab)

JPKCom Gutenberg Image Block Alt-Attribute — Anleitung & Tipps

Alt-Texte von Gutenberg-Bildblöcken in WordPress dynamisch und SEO-freundlich aktualisieren — Installation und Praxis-Hinweise zum JPKCom-Plugin.

JPKCom Gutenberg Image Block Alt-Attribute sorgt für SEO-freundliche, dynamische Aktualisierungen der Alt-Texte von Gutenberg-Bildblöcken. Das Plugin arbeitet ohne Einstellungsseite — nach der Aktivierung greift es automatisch.

Anleitung

Voraussetzungen

  • WordPress 7.0 oder neuer (getestet bis WordPress 7.1)
  • PHP 8.3 oder neuer

Installation

  1. Gehe im Admin-Bereich zu Plugins → Installieren und klicke auf Plugin hochladen.
  2. Wähle die ZIP-Datei des Plugins und klicke auf Jetzt installieren.
  3. Klicke auf Aktivieren — das Plugin ist sofort einsatzbereit.

Es gibt keine Einstellungsseite. Sobald das Plugin aktiv ist, werden die Alt-Attribute der Bildblöcke dynamisch aktualisiert.

Lücken finden: die Abilities API

Seit Version 1.1.0 registriert das Plugin eine nur lesende Ability, jpkcom-gutenberg-img-alt/list-images-missing-alt. Die Abilities API ist ein WordPress-Kernregister maschinenlesbarer Fähigkeiten — ein KI-Assistent, ein MCP-Client oder REST-Automatisierung kann darüber fragen, für welche Bilder dieses Plugin nichts einzusetzen hat.

Das ist die nützlichere Frage als „welche Bilder haben keinen Alt-Text": Weil das Plugin den Alt-Text zur Render-Zeit vom Anhang in der Mediathek holt, repariert ein einziges Ausfüllen dort jeden core/image-Block, der auf diesen Anhang verweist. Kein Beitrag muss neu gespeichert, kein Block-Markup angefasst werden. Was der Mechanismus nicht kann, ist einen Alt-Text erfinden, den der Anhang nicht hat — und genau diese Restlücke meldet die Ability.

Gemeldet wird nicht bloß „leer": Die Ability unterscheidet fünf Fälle und benennt jeden einzeln über das Feld reason, statt sie zusammenzuzählen. Zwei davon sehen in der Mediathek gesetzt aus, wirken aber nicht:

  • zero — eine einzelne 0. PHP behandelt sie als leer, die Einsetzung überspringt sie.
  • whitespace_only — ein Alt-Text, der nur aus Leerzeichen besteht, wird ebenfalls übersprungen.

Zwei weitere sind schlicht leer, aber nicht dasselbe:

  • empty — es ist ein Wert gespeichert, und der ist leer.
  • no_row — für dieses Bild wurde nie ein Alt-Text gespeichert.

Den fünften Fall gibt es seit 1.2.0. Über die Mediathek entsteht er nie, nur wenn Code _wp_attachment_image_alt direkt schreibt:

  • not_text — gespeichert ist ein serialisiertes Array, Objekt oder ein anderer Wert, der kein Text ist. Ein Array setzte das Plugin bis 1.1.0 als wörtliches Array ein, samt PHP-Warnung; seit 1.2.0 setzt es nur noch Text ein und lässt den Block sonst unverändert.

So ist erkennbar, ob das Feld nie gefüllt wurde, geleert wurde oder mit etwas gefüllt ist, das nicht funktioniert.

Die Ability verlangt die Fähigkeit upload_files — bewusst strenger als bei den Geschwister-Plugins von JPKCom, die Inhalte veröffentlichen, welche die Site Besuchern ohnehin zeigt. Diese hier zählt die Mediathek auf, deshalb sind Abonnenten ausgeschlossen. Komplett abschalten in der wp-config.php:

define( 'JPKCOM_GUTENBERG_IMG_ALT_ABILITIES', false );

Enger ziehen lässt sich das über den Filter jpkcom_gutenberg_img_alt_ability_capability; wie die Ability nach außen sichtbar ist (REST-Route, MCP-Freigabe, Annotationen), steuert jpkcom_gutenberg_img_alt_ability_meta.

Tipps & Tricks

  • Aussagekräftige Alt-Texte zahlen auf SEO ein: Gute Alt-Attribute helfen sowohl Suchmaschinen als auch Screenreadern. Das Plugin hält die Alt-Texte im core/image-Block dynamisch aktuell.
  • Aktivieren und vergessen: Da es keine Konfiguration gibt, ist nach der Aktivierung nichts weiter einzustellen.
  • $-Zeichen im Alt-Text — Update auf 1.0.8 empfohlen: Enthielt ein Alt-Text die Zeichenfolgen $1, ${1}, $2 oder \1, zerstörte das bis Version 1.0.7 das gerenderte <img>-Tag. Diese Sequenzen sind Rückverweise innerhalb der Ersetzung, sodass ganz normaler redaktioneller Text — ein Preis, eine Versionsnummer — durch einen Teil des Bild-Tags ersetzt wurde. Im Fall $2 wurde das Tag vorzeitig geschlossen und der Rest landete als sichtbarer Text auf der Seite. Gefunden und behoben von @yoldaolmak (öffnet in neuem Tab) (Kemal Kaya).
  • Robuster seit 1.2.0: Den Alt-Text setzt das Plugin jetzt mit dem HTML Tag Processor von WordPress (WP_HTML_Tag_Processor) statt mit einem regulären Ausdruck. Der kam nur mit genau dem Markup zurecht, das der Core erzeugt, und versagte sonst still — er konnte etwa data-alt statt alt überschreiben. Hat das <img> eines Bildblocks gar kein alt-Attribut, bekommt es jetzt eines; vorher ließ sich nur ein vorhandenes umschreiben. Und ein Alt-Text, der wörtlich &amp; enthält, erscheint jetzt so, wie du ihn eingetippt hast.
  • Leerzeichen-Alt-Texte: Besteht ein Alt-Text nur aus Leerraum, überschreibt er seit 1.0.8 nicht mehr das bereits im Markup vorhandene alt-Attribut.
  • Übersetzbar seit 1.1.0: Übersetzbare Strings gab es zwar schon seit 1.0.2 im Updater, aber ohne Text Domain-Header — sie waren damit weder extrahierbar noch ladbar. Mit 1.1.0 kamen Text Domain- und Domain Path-Header sowie eine Übersetzungs-Vorlage dazu; der Großteil der Texte stammt aus der neuen Ability. Fertige Sprachdateien liegen noch nicht bei.
  • Reproduzierbare Updates: Ab Version 1.0.2 nutzt das Plugin sichere, selbst gehostete Updates über GitHub mit SHA256-Prüfsummen und arbeitet mit declare(strict_types=1). Seit 1.2.1 trägt es außerdem den Header Update URI: Die Update-Schnittstelle von wordpress.org liefert für dieses Plugin dann keine Updates mehr, ein dort veröffentlichtes Plugin mit demselben Slug kann sich also nicht als Update ausgeben.
  • Updates auch im deaktivierten Zustand (seit 1.2.3): Mit Updater 1.5.0 bedient ein einziger geladener JPKCom-Updater alle installierten JPKCom-Plugins, aktive wie deaktivierte — mit Update-Zeile, Icon und „Details anzeigen" und derselben SHA256-Prüfung. Für dieses Plugin im deaktivierten Zustand heißt das: Es braucht ein anderes aktives JPKCom-Plugin mit Updater 1.5.0 oder neuer, auf Multisite netzwerkweit aktiv oder auf der Hauptsite. Download-Adressen von JPKCom-Plugins stehen nicht mehr in der gespeicherten Update-Liste, sondern kommen nur zurück, solange ein JPKCom-Updater geladen ist; die Prüfsumme gilt auch für Pakete, die ein anderes Plugin liefert, und für jede GitHub-Adresse der Release-Datei. Liegt das Plugin als Git-Checkout (oder anderen Versionskontroll-Checkout) oder in einem umbenannten Ordner, erfährst du von neuen Versionen, automatisch aktualisiert wird es aber nie — ein deaktiviertes Plugin in einem umbenannten Ordner findet der Updater allerdings gar nicht, dafür gibt es also auch keinen Hinweis. Update-Infos holt der Updater nur für Nutzer, die Plugins aktualisieren dürfen, im Update-Cron und in WP-CLI — nie für anonyme Besucher. Seit 1.2.2 zeigt Dashboard → Aktualisierungen außerdem das JPKCom-Logo neben dem Plugin.

Weiterführende Informationen