Inhalt
Im Gutenberg-Editor setzt die Redaktion Überschriften, Bildergalerien, Spalten und Call-to-Action-Blöcke – und im entkoppelten Frontend soll am Ende genau das erscheinen, was im Editor stand. Der Weg dahin ist die zentrale technische Frage jeder Headless-Migration mit Gutenberg. Es gibt zwei Antworten: fertig gerendertes HTML aus der API einbinden oder strukturierte Block-Daten auf eigene Frontend-Komponenten mappen. Wie das Backend grundsätzlich vom Frontend entkoppelt wird, ordnet der Beitrag dazu ein, was Headless WordPress technisch ist.
Der erste Weg ist in einer Stunde produktiv, kostet aber Kontrolle. Der zweite gibt dem Frontend volle Hoheit über das Markup, kostet dafür Pflegeaufwand pro Block-Typ. Dieser Beitrag zeigt beide Wege, das oft unterschätzte Styling-Problem und den ehrlichen Sonderfall: Page-Builder, die Headless faktisch brechen.
Wie kommen Gutenberg-Blöcke ins Frontend?
Gutenberg-Blöcke gelangen über zwei Hauptwege ins Headless-Frontend. Erstens als fertig gerendertes HTML aus REST API oder WPGraphQL, das sich direkt einbinden lässt. Zweitens als strukturierte Block-Daten, die das Frontend auf eigene Komponenten abbildet. Der erste Weg ist schnell, der zweite gibt volle Markup-Kontrolle – beide sind legitim, je nach Projekt.
Dass dieser Weg überhaupt zentral ist, liegt an der Verbreitung des Block-Editors: Im WordPress-Jahres-Survey 2023 gaben 39,9 % der Teilnehmenden an, den Block-Editor zu nutzen, weitere 19,9 % Block- und Classic-Editor gemischt (WP Tavern, WordPress 2023 Survey, 20. Februar 2024). Wer heute eine Headless-Migration plant, trifft also mit hoher Wahrscheinlichkeit auf Gutenberg-Inhalte.
Der Unterschied liegt darin, wo das Markup entsteht. Beim ersten Weg rendert WordPress, beim zweiten das Frontend. WordPress speichert Block-Inhalte als Markup mit eingebetteten HTML-Kommentaren im Feld post_content – diese Kommentare tragen die Block-Attribute. Welcher Weg passt, hängt davon ab, wie viel das Frontend an Darstellung, Interaktivität und Komponenten-Wiederverwendung selbst steuern soll. Wer nur einen Blog-Artikel originalgetreu anzeigen will, kommt mit HTML weit. Wer aus einem Galerie-Block eine interaktive React-Komponente bauen will, braucht die strukturierten Daten.
Der schnelle Weg: rohes HTML aus der API
Der schnellste Weg ist fertig gerendertes HTML. WordPress liefert Gutenberg-Inhalte über REST API und WPGraphQL standardmässig als bereits gerendertes HTML: Das Block-Markup aus post_content wird durch Filter gejagt, die die Blöcke parsen und vollständiges HTML erzeugen. Dieses HTML lässt sich im Frontend über dangerouslySetInnerHTML einbinden (Kinsta, Headless WordPress und Gutenberg).
Für viele Projekte reicht das. Ein einsprachiger Marketing-Blog, dessen Artikel aus Text, Bildern und Standard-Blöcken bestehen, ist mit diesem Ansatz in kurzer Zeit live. Die Redaktion arbeitet im gewohnten Editor, das Frontend zeigt das Ergebnis, niemand muss pro Block-Typ eine Komponente pflegen. Aus eigenen Schweizer Projekten 2024–2026: Für einen reinen Content-Blog mit rund 40 Bestandsartikeln war der HTML-Weg in unter einem Tag eingerichtet, während der strukturierte Ansatz für dieselbe Seite mehrere Tage Komponentenarbeit bedeutet hätte – ohne sichtbaren Mehrwert für den Leser.
Der Haken zeigt sich erst, wenn das Frontend mehr will als nur anzeigen. Genau dort beginnt der strukturierte Ansatz.
Der saubere Weg: strukturierte Block-Daten
Der strukturierte Weg liefert Blöcke als Daten statt als HTML. Das Plugin WPGraphQL Content Blocks von WP Engine erweitert WPGraphQL um ein editorBlocks-Feld auf Post und Page und gibt jeden Block mit __typename, name und seinen Attributen zurück. Damit kann das Frontend pro Block-Typ entscheiden, welche Komponente es rendert – statt fremdes HTML zu übernehmen.
Voraussetzung ist WPGraphQL selbst, ein kostenloses Open-Source-Plugin, das mindestens WordPress 6.0 erfordert (WPGraphQL im Plugin-Verzeichnis). Auf diese Frage – GraphQL oder REST – geht der Beitrag zu WPGraphQL gegen die REST API im Detail ein. Verschachtelte Blöcke, etwa Spalten in einem Spalten-Container, lassen sich über das Argument flat:true flach zurückgeben; die Hierarchie bleibt über clientId und parentClientId rekonstruierbar. Custom Blocks – eigene, projektspezifische Block-Typen – registriert das Plugin automatisch als eigene GraphQL-Typen, sodass sie sich über ein on [BlockTypeName]-Fragment gezielt abfragen lassen (WPGraphQL Content Blocks, Plugin-Dokumentation).
So entsteht ein sauberes Mapping: Der Block core/heading rendert eine <Heading>-Komponente, core/image eine optimierte <Image>-Komponente des Frontend-Frameworks, ein Custom-Block acme/cta eine eigene Call-to-Action-Komponente. Das Frontend behält die volle Kontrolle über Markup, Klassen und Verhalten.
Fertiges HTML zeigt, was war. Strukturierte Block-Daten erlauben, daraus zu bauen, was sein soll.
Wie sich diese saubere Trennung auf die Redaktion auswirkt – und warum die Editor-Erfahrung dabei erhalten bleiben muss – behandelt der Beitrag zur Redaktions- und Editor-Erfahrung im Headless-Setup.
Was kostet die Styling-Treue?
Die grösste unterschätzte Hürde ist nicht das HTML, sondern das CSS. Gutenberg injiziert Stile inline und vergibt dynamisch generierte Klassennamen, sodass der blosse Import der Block-Stylesheets das tatsächliche Styling nicht abbildet. Rohes HTML aus der REST API ist ohne dieses passende CSS schlicht nicht originalgetreu darstellbar – die Blöcke kommen optisch „nackt" an.
Konkret heisst das: WordPress generiert für Block-Stützen wie Abstände, Farben oder Ausrichtung Inline-CSS-Blöcke (etwa global-styles-inline-css und core-block-supports-inline-css) erst beim Rendern der Seite – Stile, die im klassischen WordPress automatisch mitgeliefert werden, im Headless-Frontend aber fehlen. Das zugehörige GitHub-Issue zur Extraktion dieses inline injizierten CSS speziell für Headless-Setups ist seit September 2023 offen (WordPress/gutenberg Issue #54510). Es gibt also bis heute keinen offiziellen, sauberen Weg, das vollständige Block-CSS aus WordPress herauszuziehen.
In der Praxis bedeutet das Mehrarbeit, egal welchen Weg man wählt. Beim HTML-Ansatz muss das Frontend-Team die relevanten Block-Stile gezielt nachbauen oder das Gutenberg-Stylesheet manuell einbinden und anpassen. Beim strukturierten Ansatz entsteht das Markup ohnehin im Frontend – dort gibt man den Komponenten von Anfang an das eigene Design-System mit, was das Problem entschärft, aber den Aufwand pro Block-Typ erhöht. Aus eigenen Schweizer Projekten 2024–2026: Schon ein Set von rund einem Dutzend regelmässig genutzter Standard-Blöcke – Überschrift, Absatz, Bild, Galerie, Spalten, Buttons, Liste, Zitat und einige mehr – musste einzeln nachgebaut werden, und die Styling-Angleichung war dabei regelmässig der grössere Posten als die Datenanbindung selbst – planbar, aber nie „kostenlos".
Roh-HTML oder strukturiertes Parsing – was passt?
Die Wahl hängt davon ab, wie viel Kontrolle das Frontend über Markup und Interaktivität braucht. Roh-HTML passt für reine Anzeige-Inhalte und schnelle Projekte; strukturiertes Parsing passt, wenn Blöcke zu eigenen Komponenten werden sollen oder das Design-System eng kontrolliert wird. Ein Hybrid – strukturierte Daten plus renderedHtml als Fallback – ist oft der realistische Mittelweg.
Denn WPGraphQL Content Blocks bietet pro Block zusätzlich ein renderedHtml-Feld. So lässt sich editorBlocks mit name, __typename, renderedHtml, id und parentId abfragen und je Block entscheiden: bekannte Block-Typen über eigene Komponenten aus den strukturierten Attributen rendern, unbekannte oder selten genutzte Blöcke über ihr server-gerendertes renderedHtml als Fallback ausspielen (WPGraphQL Content Blocks README). Das vermeidet die Alles-oder-nichts-Falle.
| Projekt-Profil | Empfehlung | Warum |
|---|---|---|
| Einsprachiger Content-Blog, Standard-Blöcke, schnell live | Roh-HTML via API | In Stunden produktiv; keine Komponenten-Pflege; Styling über importiertes Block-CSS |
| Marketing-Site mit Custom Blocks und eigenem Design-System | Strukturiertes Parsing | Volle Markup-Kontrolle; Blöcke werden zu Frontend-Komponenten; typisierte Attribute |
| Grosse Bestands-Site, viele Block-Varianten, schrittweise Migration | Hybrid: Daten + renderedHtml-Fallback | Bekannte Blöcke sauber gemappt, der lange Rand-Tail über server-gerendertes HTML |
| Site mit Page-Builder (Elementor, Divi) | Erst Editor klären | Builder erzeugen eigenen Output; Gutenberg-Block-Pfad greift nicht ohne Umbau |
Für die Ökosystem-Stabilität spricht, dass der GraphQL-Block-Pfad offiziell getragen wird: WPGraphQL wurde am 7. Oktober 2024 zum kanonischen Plugin auf WordPress.org, im Zuge dessen sein Schöpfer Jason Bahl nach dreieinhalb Jahren bei WP Engine zu Automattic wechselte (WP Tavern, WPGraphQL wird kanonisches Plugin). Der zugrunde liegende GraphQL-Layer steht damit auf stabilerem Fundament als ein reines Drittanbieter-Plugin.
Was dieser Ansatz nicht löst – der ehrliche Teil
Hier wird die Bilanz unbequem. Keiner der beiden Wege ist gratis, und ein Sonderfall bricht Gutenberg-Headless faktisch.
Roh-HTML untergräbt das Grundprinzip der Entkopplung. Wer HTML als API nutzt, gibt einen Grossteil dessen auf, wofür entkoppelte Systeme gebaut werden. Die rohen Block-Attribute, die Gutenberg als Kommentare im Inhalt speichert, sind nicht mehr verfügbar, sobald der Inhalt für die Öffentlichkeit gerendert ist. Und der Versuch, aus dem fertigen HTML doch wieder data-Attribute auf React- oder Vue-Komponenten zu mappen, ist brüchig und schwierig, weil alle Attribute als untypisierte Strings ankommen (Jason Bahl, Gutenberg und entkoppelte Anwendungen). Roh-HTML ist also schnell, aber eine Sackgasse, sobald das Frontend strukturell mit den Inhalten arbeiten will.
Strukturiertes Parsing kostet Pflege pro Block-Typ. Damit komplexe, verschachtelte Attribute einzeln abfragbar sind, müssen typisierte Objekt-Attribute explizit definiert werden – entweder über eine typed_object_attributes-Property der Block-Klasse oder über den Filter wpgraphql_content_blocks_object_typing_{block-name} (WPGraphQL Content Blocks, Plugin-Dokumentation). Jeder Custom Block und jede tiefere Attributstruktur ist damit ein Stück Pflegearbeit, das mitwächst, wenn die Redaktion neue Block-Typen bekommt. Sauber, aber nicht wartungsfrei.
Das Styling bleibt Handarbeit. Wie oben gezeigt: Das inline injizierte Block-CSS kommt nicht mit der API, und das offizielle Issue dazu ist offen. Es gibt keinen Knopf, der das Editor-Styling originalgetreu ins Frontend bringt – das Frontend-Team baut die relevanten Block-Stile nach.
Page-Builder brechen den Gutenberg-Pfad. Das ist der Sonderfall, der ganze Projekte ausbremst. Viele Sites nutzen nicht Gutenberg, sondern einen Page-Builder. Elementor allein hat über zehn Millionen aktive WordPress-Installationen und gehörte im Mai 2024 zu nur vier Plugins, deren Active-Install-Anzeige im Verzeichnis über zehn Millionen angehoben wurde – neben Contact Form 7, Yoast SEO und Classic Editor (WP Content, Plugin-Verzeichnis hebt Active-Install-Limit an). Solche Builder erzeugen ihren eigenen Output statt sauberer Gutenberg-Blöcke: Elementor hinterlässt dabei vergleichsweise lesbares HTML, Divi ist stärker shortcode-abhängig. In beiden Fällen lässt sich der Inhalt nicht ohne Weiteres als strukturierte Blöcke abfragen, und das Frontend muss builder-spezifisches Markup verarbeiten – oder der Content wird vor der Headless-Migration auf Gutenberg umgestellt. Wer Headless plant und heute mit einem Page-Builder arbeitet, sollte diese Editor-Frage zuerst klären, bevor irgendein Block-Parsing zum Thema wird.
Kurz: Gutenberg lässt sich sauber entkoppeln, aber nur, wenn die Redaktion auch tatsächlich mit Gutenberg arbeitet und das Team den Aufwand für Styling und Block-Pflege einplant.
Wo Ihre Inhalte heute stehen – der schnelle Check
Bevor man über das Block-Rendering entscheidet, lohnt der Blick auf den Ist-Zustand der bestehenden Site. Der kostenlose Website-Check prüft sichtbare Indikatoren von aussen und gibt eine erste Standortbestimmung – etwa ob die Seite bereits Performance- und Struktur-Reserven hat, die für eine entkoppelte Architektur sprechen. Welche Editor-Basis im Backend liegt – Gutenberg oder ein Page-Builder – klären wir anschliessend gemeinsam, denn genau diese Frage entscheidet über den Migrationsweg.
Wer die grundsätzliche Architektur-Entscheidung sucht, findet sie auf der Themenseite zu Headless WordPress; wie wir ein solches Projekt von der Analyse bis zum Frontend begleiten, zeigt die Übersicht unserer Leistungen.
Nächster Schritt
Ob Roh-HTML reicht oder strukturiertes Block-Parsing den Aufwand wert ist, hängt an Ihren Inhalten: Wie viele Custom Blocks, wie eng das Design-System, welcher Editor im Backend. Diese Punkte lassen sich in einem kurzen Gespräch sauber einordnen – inklusive einer ehrlichen Aufwandsschätzung für die Styling-Treue. Wenn Sie eine Headless-Migration mit Gutenberg planen, vereinbaren wir gerne ein Erstgespräch — 15 Minuten, kostenlos.
Wer zuerst die technischen Grundlagen vertiefen will, findet in der Architektur-Kategorie im Blog die passenden Beiträge zu API-Wahl, Editor-Erfahrung und Migration.