Migration zu Next.js / Astro in Essen

Wer in Essen eine gewachsene WordPress-Seite ablösen will, stellt meist zuerst die Frage nach dem Design. Die schwierigere Frage ist eine andere: Was genau steckt in der Datenbank, und wie kommt es heraus? Ich bin Mariusz Szatkowski, arbeite seit 2006 mit WordPress und migriere Seiten als einzelner Entwickler, remote und schriftlich. Diese Seite beschreibt nur diesen einen Schritt: den Inhalt aus WordPress holen, bereinigen und in Markdown, MDX oder ein Headless-CMS überführen.

Foto: Tuxyso, CC BY-SA 4.0, Wikimedia Commons.

#Welche Wege aus WordPress heraus gibt es?

Es gibt drei, und sie liefern nicht dasselbe. Welche ich nehme, hängt davon ab, was Ihre Seite enthält.

Quellen: Tools Export screen, REST API Pagination, WPGraphQL Custom Post Types.

Oft kombiniere ich zwei: die WXR-Datei für den Gesamtbestand und die REST API für Medien oder einzelne Felder, die im Export fehlen oder anders aussehen.

#Was liefert der WXR-Export, und was nicht?

WXR steht für WordPress eXtended RSS. Die Datei entsteht unter Werkzeuge, Export mit der Schaltfläche zum Herunterladen. Nach der WordPress-Dokumentation enthält sie Beiträge, Seiten, eigene Inhaltstypen, Kommentare, Custom Fields, Kategorien, Tags, eigene Taxonomien und Benutzer. Für Beiträge und Seiten lässt sich nach Autor, Zeitraum und Status filtern, bei Beiträgen auch nach Kategorie.

Das hilft bei der Planung. Wenn Sie nur Beiträge der letzten Jahre brauchen, exportiere ich gefiltert und halte die Datei klein. Brauche ich alles, nehme ich den Gesamtexport.

Zwei Dinge klären wir vorher schriftlich:

• Personenbezogene Daten. Kommentare und Benutzer stehen in derselben Datei. Ich übernehme nur, was die neue Seite wirklich anzeigt, und lösche die Exportdatei nach der Migration.
• Medien. Die Dokumentation zählt Mediendateien nicht als Inhalt der Datei auf. Die Bilder hole ich deshalb über die Medien-Endpunkte oder direkt aus dem Upload-Ordner.

#Wie hole ich mit der REST API alle Datensätze?

Die API liefert nach der Dokumentation höchstens 100 Datensätze je Anfrage (per_page). Gesamtzahl und Seitenzahl stehen in den Antwort-Headern X-WP-Total und X-WP-TotalPages. Ein Skript fragt die erste Seite ab, liest X-WP-TotalPages und holt den Rest in einer Schleife:

curl -si "https://example.com/wp-json/wp/v2/posts?per_page=100&page=1" \
  | grep -i "^x-wp-total"

Beim Sortieren gilt: Sammlungen mit Datum kommen standardmäßig absteigend nach Datum. Für einen reproduzierbaren Lauf setze ich orderby und order ausdrücklich, damit zwei Läufe dieselbe Reihenfolge ergeben und ich Abweichungen sofort sehe.

Ich speichere jede Antwort unverändert als JSON-Datei, bevor ich irgendetwas umwandle. So kann ich die Umwandlung beliebig oft wiederholen, ohne Ihre alte Seite erneut zu belasten.

#Was bringt WPGraphQL?

WPGraphQL liefert nur die Felder, die die Abfrage nennt. Für eine Migration ist das praktisch, wenn Beiträge, Autoren, Kategorien und Medien in einem Zug in eine Datei sollen:

{
  posts(first: 100) {
    nodes { id title date slug content }
  }
  mediaItems(first: 100) {
    nodes { id title altText sourceUrl }
  }
}

Vier Punkte aus der WPGraphQL-Dokumentation, die den Ablauf bestimmen:

• Ein eigener Inhaltstyp erscheint im Schema nur mit show_in_graphql. Fehlt das, muss ich es in der Registrierung ergänzen.
• WPGraphQL liefert veröffentlichte Einträge an anonyme Anfragen nur, wenn der Typ öffentlich oder öffentlich abfragbar registriert ist.
• Verbindungen liefern standardmäßig höchstens 100 Einträge je Seite, sodass ich auch hier seitenweise abfrage.
• Öffentliche Introspektion ist standardmäßig aus. Für einen Build, der das Schema braucht, gibt es wp graphql generate-static-schema oder eine authentifizierte Abfrage.

Quellen: Custom Post Types, Security, Media.

Ob die Erweiterung auf Ihrer Seite überhaupt installiert werden soll, entscheide ich zurückhaltend. Für einen einmaligen Export genügt oft die REST API, und jede zusätzliche Erweiterung auf der Altseite ist ein weiteres Risiko, das ich Ihnen vorher nenne.

#Wie behandle ich Medienbibliothek und Bildgrößen?

Der Medien-Endpunkt der REST API liefert je Datei unter anderem source_url, alt_text, caption, description, media_type, media_details und die zugehörige Beitrags-ID. Daraus entsteht eine Tabelle: Datei, Alternativtext, Bildunterschrift, Beitrag, in dem sie vorkommt.

Zu den Bildgrößen:

• WordPress erzeugt aus jedem Bild mehrere Größen. In den Medieneinstellungen stehen Miniatur, mittel und groß, Themes können weitere Größen registrieren.
• Ist das Original größer als der Schwellwert, skaliert WordPress es herunter. Der Filter big_image_size_threshold hat nach der Dokumentation den Standardwert 2560 Pixel, und false schaltet die Skalierung ab.
• Für die neue Seite nehme ich nicht die erzeugten Zwischengrößen, sondern das Original oder die skalierte Fassung und lasse die neue Pipeline die Größen selbst erzeugen. So hängt kein Bild an den Größenstufen des alten Themes.

Wichtig ist der Abgleich: Jeder Verweis auf /wp-content/uploads/ im Text muss ein Ziel haben. Ich suche alle Pfade im exportierten Inhalt, vergleiche sie mit der Medienliste und melde Verweise ohne Datei, bevor sie auf der neuen Seite als kaputte Bilder auftauchen. Fehlende Alternativtexte nenne ich Ihnen als Liste, denn die ergänze ich nicht erfunden, sondern Sie oder Ihre Redaktion tun das.

#Was machen Shortcodes in den Inhalten?

Shortcodes sind Platzhalter wie [gallery id="123"]. Nach der Dokumentation ersetzt WordPress sie bei der Ausgabe von the_content durch das, was die Handler-Funktion zurückgibt. Daraus folgen zwei Dinge für den Export:

1. Der gespeicherte Inhalt enthält den Platzhalter, der ausgegebene Inhalt das Ergebnis. Ich muss also pro Shortcode entscheiden, welche Fassung ich brauche.
2. Wird die Erweiterung entfernt, ist der Shortcode laut Dokumentation nur noch gewöhnlicher Text und würde als [gallery id="123"] auf der neuen Seite stehen.

Ich gehe so vor:

1. Alle Shortcode-Namen im Bestand auflisten und zählen.
2. Je Name festlegen: zu Markdown, zu einer Komponente oder streichen. Eine Galerie wird eine Bildliste, ein Kontaktformular ein Formular der neuen Seite.
3. Verschachtelte Shortcodes gesondert prüfen. Der WordPress-Parser kommt nach der Dokumentation nicht mit einem Shortcode zurecht, der einen gleichnamigen umschließt. Ich suche solche Stellen gezielt, damit sie nicht unbemerkt falsch umgewandelt werden.

Shortcodes für Karten, Videos oder Formulare binden oft Drittdienste ein. Das betrifft § 25 TDDDG, dazu unten mehr.

#Gutenberg-Blöcke, Elementor und Divi: wie liegt das Layout in den Daten?

Gutenberg. Blöcke werden als HTML mit Kommentaren als Begrenzer gespeichert, die Attribute als JSON enthalten können, etwa <!-- wp:paragraph {"key": "value"} -->. Das ist für eine Migration günstig: Die Struktur ist maschinenlesbar. parse_blocks() zerlegt den Inhalt laut Dokumentation in einen Baum aus Blöcken, Text außerhalb von Blöcken erscheint als Block ohne blockName. Die Funktion kann bei tief verschachtelten Dokumenten viel Speicher brauchen; für große Bestände gibt es WP_Block_Processor als streamenden Parser. Aus dem Baum erzeuge ich Markdown: Absatz, Überschrift, Liste, Bild und Zitat sind einfach, eigene und Plugin-Blöcke einzeln zu klären.

Elementor. Das Layout liegt nach der Entwicklerdokumentation als JSON in einem privaten Custom Field in wp_postmeta, nicht im Beitragstext. Der Beitragstext allein sagt daher wenig. Ich lese das JSON, ordne Widgets Textblöcken, Bildern und Schaltflächen zu und verwerfe Abstände und Stile, denn die entstehen in der neuen Seite aus Ihrem Layout neu. Ein Elementor-Template lässt sich auch als JSON-Datei exportieren.

Divi und andere Page Builder. Hier hängt es von Version und Einstellung ab, wo das Layout liegt. Ich schaue zuerst in einen echten Datensatz, bevor ich einen Umwandler plane, und nenne Ihnen den Aufwand erst danach.

Quellen: Block-Editor, Key Concepts, parse_blocks, Elementor Data Structure.

Bei Page-Builder-Seiten gilt: Das optische Layout bekomme ich nicht aus den Daten, sondern aus Ihren Vorgaben. Mockups und Wireframes liefern Sie, ich setze sie um.

#Wie kommen Custom Fields in den Export?

Custom Fields sind Meta-Felder. Im WXR-Export stehen sie laut Dokumentation mit drin. In der REST API sieht das anders aus: Ein Meta-Feld erscheint nur, wenn es mit show_in_rest registriert wurde, und der Standardwert ist false. Ein eigener Inhaltstyp muss außerdem Custom Fields unterstützen. Für Felder vom Typ Array verlangt WordPress ein Schema der Einträge unter show_in_rest.schema.items.

Das heißt in der Praxis: Felder, die ein Plugin wie ACF anlegt, sind über die API nicht automatisch sichtbar. Ich lese sie dann aus dem WXR-Export oder ergänze die Registrierung vorübergehend auf einer Kopie der Seite. An der Live-Seite ändere ich dafür nichts, ohne es mit Ihnen schriftlich abzustimmen.

Für jedes Feld halte ich in einer Tabelle fest: Name, Typ, Beispielwert, wie oft es gefüllt ist und wohin es im neuen Modell geht. Felder ohne Ziel nenne ich Ihnen, bevor ich sie weglasse.

#Wohin mit den bereinigten Inhalten: Markdown, MDX oder Headless-CMS?

Nach dem Bereinigen hängt das Ziel daran, wer künftig pflegt.

• Markdown oder MDX im Repository. Passt, wenn eine oder wenige Personen selten ändern. Inhalte liegen versioniert neben dem Code, jede Änderung ist nachvollziehbar. MDX erlaubt Komponenten im Text, etwa für Hinweisboxen oder Tabellen.
• Headless-CMS. Passt, wenn mehrere Redakteure ohne Entwickler veröffentlichen sollen. Dann übertrage ich die Inhalte per Import in das CMS und baue das Inhaltsmodell dort nach.

Beides setze ich nach Ihrem Bedarf um. Die Entscheidung dokumentiere ich schriftlich, damit sie in einem Jahr nachvollziehbar bleibt.

Die Umwandlung selbst ist ein wiederholbares Skript: Rohdaten rein, Markdown oder CMS-Import raus. Auf Stichproben folgt ein Vergleich der Wortzahl je Seite zwischen alter und neuer Fassung, damit ein abgeschnittener Absatz auffällt. Die URLs übernehme ich ins Redirect-Inventar, wie auf der Seite zur Migration zu Astro und Next.js beschrieben.

#Was gilt für Essener Unternehmen nach DDG, TDDDG und LDI NRW?

Beim Umbau werden diese Pflichten gern vergessen, weil Footer und Skripte neu gebaut werden. Keine Rechtsberatung, sondern der Prüfpunkt aus Entwicklersicht:

• Impressum. § 5 DDG verlangt für geschäftsmäßige, in der Regel gegen Entgelt angebotene digitale Dienste unter anderem Name und Anschrift sowie Angaben für eine schnelle elektronische Kontaktaufnahme, leicht erkennbar und unmittelbar erreichbar. Ein Shortcode oder Footer-Widget, das das Impressum bisher ausgab, muss in der neuen Seite einen Ersatz haben.
• Drittdienste in Inhalten. Eingebettete Karten, Videos oder Formulare aus Shortcodes greifen oft auf das Endgerät zu. § 25 TDDDG erlaubt Speicherung und Zugriff nur mit Einwilligung des Endnutzers, soweit keine Ausnahme nach Absatz 2 greift. Ich liste auf, welche Einbettungen der Altbestand hat, damit Sie sie bewerten können.
• Aufsicht. Für private Unternehmen in Nordrhein-Westfalen ist die Landesbeauftragte für Datenschutz und Informationsfreiheit (LDI NRW) zuständig.

Quellen: § 5 DDG, § 25 TDDDG, LDI NRW.

#Checkliste vor dem Export

Auch ohne mich nützlich:

#So läuft ein Export-Projekt mit mir

1. Sie schicken mir Adresse, Ziel und Termin. Ich antworte schriftlich mit Rückfragen.
2. Ich lese nach Absprache mit Leserechten oder aus einer Exportdatei und erstelle das Inventar aus der Checkliste.
3. Sie erhalten schriftlich Umfang, Annahmen und Ausschlüsse. Das Layout kommt von Ihnen.
4. Ich bereinige und wandle um, zeige Ihnen das Ergebnis auf einer Staging-Seite und Sie nehmen es ab.
5. Auf Wunsch betreue ich die neue Seite danach weiter.

Ich antworte an Werktagen schriftlich. Es gibt keine Termine und keine Anrufe, alles läuft per Text.

#Häufige Fragen

#Reicht der WordPress-Export als Datenquelle?

Für Beiträge, Seiten, Kategorien und Custom Fields oft ja. Medien, Shortcode-Ergebnisse und das Layout eines Page Builders deckt die WXR-Datei nicht allein ab. Dafür nehme ich die REST API oder WPGraphQL dazu und lege vorher schriftlich fest, welche Quelle für welches Feld gilt.

#Was passiert mit Shortcodes, wenn die Erweiterung wegfällt?

Ein nicht mehr registrierter Shortcode ist nach der WordPress-Dokumentation gewöhnlicher Text. Ich inventarisiere deshalb jeden Shortcode im Bestand und entscheide je Fall: in Markdown überführen, durch eine Komponente ersetzen oder streichen.

#Muss ich meine Inhalte in Markdown umwandeln?

Nein. Bei einem überschaubaren Auftritt sind Markdown oder MDX im Repository eine gute Wahl. Pflegen mehrere Personen regelmäßig Inhalte, kann ein Headless-CMS sinnvoller sein. Meine Empfehlung steht samt Begründung in meiner schriftlichen Einschätzung.

#Welche Daten im Export sind datenschutzrechtlich heikel?

Der WXR-Export enthält laut Dokumentation auch Kommentare und Benutzer. Das sind personenbezogene Daten. Ich übernehme nur, was die neue Seite braucht, und gebe die Exportdatei nicht weiter. Für Ihre Datenschutzerklärung ist die LDI NRW die Aufsichtsbehörde; Rechtsberatung ersetzt das nicht.

#Welche Unterlagen brauche ich von Ihnen für den Start?

Die Adresse der Seite, einen Zugang mit Leserechten oder eine Exportdatei, die Liste der aktiven Erweiterungen und Ihr Ziel. Das Layout, also Mockups und Wireframes, kommt von Ihnen. Mein erster schriftlicher Aufschlag ist unentgeltlich.

#Schreiben Sie mir zu Ihrer WordPress-Seite

Schicken Sie mir über das Kontaktformular die Adresse Ihrer Seite in Essen, Ihr Ziel, Ihren Termin und den heutigen Stack, dazu die Liste der aktiven Erweiterungen, wenn Sie sie haben. Ich lese Ihre Angaben, frage schriftlich nach und schicke Ihnen eine erste Einschätzung, was sich leicht exportieren lässt und wo Handarbeit nötig ist. Diese erste schriftliche Einschätzung kostet nichts. Wenn Ihre Seite sich besser ohne Migration pflegen lässt, sage ich das ebenfalls.