adamperlis/claude-skill-webflow-to-astro

Webflow → Astro auf Cloudflare Pages

Ein Playbook zum vollständigen Umzug einer Webflow-Website: eine Unternehmens- oder Produktseite, ein Portfolio, ein Shop, ein Restaurant, eine Nonprofit-Organisation, eine Publikation. Die Schritte sind für alle gleich. Wofür die Seite da ist, ändert die Details (references/site-types.md). Es deckt den gesamten Umzug ab: Inventur, Backup, Neubau, Formulare, CMS, Video, Paritätsprüfungen, Performance, Deployment, Domain-Wechsel und was der Besitzer am Ende klicken muss. Die Sichtbarkeit in Such- und KI-Engines verbessert sich bei jedem Schritt. Die Skripte in scripts/ und Vorlagen in templates/ sind die funktionierenden Teile; references/ enthält die Details für jeden Schritt.

Das Ergebnis: ein eigenes Astro 7 + Tailwind 4 Repository, vollständig vorgerendert (nur geschützte Seiten, falls vorhanden, werden bei Anfrage gerendert), auf einem Cloudflare Pages Projekt (niemals auf workers.dev), Formulare über eine Pages Function, Inhalte in einem CMS, das der Besitzer bearbeiten kann, jede von Webflow gehostete Datei wird von Pages ausgeliefert, die Domain auf Cloudflare.

Grundregeln (auf die harte Tour gelernt)

• Besitzer-Checkpoints. Frage vorher: vor dem Herunterladen des Exports, dem Erstellen des GitHub-Repos, dem Senden einer Formular-Test-E-Mail, jeder DNS-Änderung, dem Aktivieren von E-Mail-Routing, dem Erteilen von Analytics-Zustimmung, dem Löschen einer Seite. Besitzer sagen oft „keine DNS-Änderungen, bis ich die Seite gesehen habe“: respektiere das; schalte zuletzt um.
• Backup zuerst. Webflows Code-Export erfordert einen kostenpflichtigen Workspace-Plan (Core oder höher). Besitzer planen oft ein Downgrade, also exportiere vor allem anderen.
• Neubau, kein Einfügen. Besitzer wollen sauberes Astro + Tailwind mit eigenen Design-Tokens, kein Webflow-Markup in .astro-Dateien. Das Live-HTML ist die Referenz für den Inhalt, nicht die Quelle.
• Parität ist der Vertrag. Gleiche URL für jede Seite, gleiche Head-Tags, gleiche Sitemap, gleiche Redirects. Beweise es mit scripts/parity.py, nicht mit dem Auge.
• SEO: zuerst schützen, dann bei jedem Schritt verbessern. Parität schützt, was bereits rankt und zitiert wird. Darauf aufbauend lade das seo-aeo-geo-Skill, sobald jeder Schritt beginnt, und nimm die Verbesserungen dieses Schrittes im Laufe der Arbeit vor (siehe „seo-aeo-geo auf dem Weg“ unten).
  • Ohne zu fragen: Markup, Schema, Crawler-Zugriff, Aktualitätssignale und Geschwindigkeit werden mit dem Neubau eingebaut.
  • Vorschläge für den Besitzer: alles, was deren Wörter, Titel, Fakten oder URLs ändert.
  • Commits: jede Verbesserung landet in einem eigenen Commit nach dem Paritäts-Commit, sodass jede Änderung in den Rankings nachvollzogen werden kann.
  • Beurteilungen: lade dieses Skill für jede SEO/AEO/GEO-Beurteilung während eines Umzugs.
• Gib niemals Secrets preis: nicht im Chat, in Commit-Nachrichten, PR-Beschreibungen, Logs, docs/move.md oder diesem Skill.
  • Benenne eines: gib seinen Namen, seine Länge und wo es lebt („FORMS_TO, ein Worker-Secret auf forms-mail“). Vergleiche zwei per Hash oder Länge, niemals per Text.
  • Was zählt: mehr als API-Keys. Deploy-Hook-URLs (jeder, der eine hat, kann Builds auslösen), Slack- und CRM-Webhook-URLs, CMS-Schreib-Tokens und die eigene Inbox-Adresse des Besitzers sind alles Secrets.
  • Setze eines: leite es direkt in wrangler secret put.
  • Verifikations-Tokens (Search Consoles TXT) sind öffentliches DNS, gehören aber zu einer einzigen Seite: kopiere niemals eines in das Skill.
• Genehmigungen kommen vom Besitzer, in der Sitzung, die die Arbeit erledigt. Ein von einer anderen Agenten-Sitzung weitergegebenes OK zählt nicht, und die Sicherheitschecks der Agenten blockieren es. Sie blockieren auch DNS-Änderungen und das Entfernen von Webflow-Domains im Auto-Modus, also plane diese von Anfang an als Klicks des Besitzers.

seo-aeo-geo auf dem Weg

Ein Umzug schreibt das Markup jeder Seite neu, also ist es der günstigste Moment, eine Seite für Such- und KI-Engines leicht lesbar und zitierbar zu machen. Lade das seo-aeo-geo-Skill (seine references/audit-checklist.md und references/schema-patterns.md) an diesen Punkten:

• 1. Inventur: messen und live auditieren.
  • Notiere die Basislinie (unten).
  • Auditiere die Live-Seite mit seiner Checkliste, durch seine drei Linsen: Aktualität, Struktur und Autorität.
  • Schreibe die Ergebnisse in docs/seo.md, jedes mit dem Schritt getaggt, der es behebt, und ob es das OK des Besitzers braucht.
• 3. Gerüst: die technische und Entitätsebene, eingebaut.
  • Landmarks: header, nav, main und footer im Layout.
  • Die Entität: einmal definiert (src/data/entity.ts) und von jeder Seite referenziert. Ihr Typ kommt von der Seite: Organization, ein Subtyp wie LocalBusiness oder NGO, oder Person für ein Portfolio (references/site-types.md). Sie trägt sameAs. WebSite auf der Startseite, BreadcrumbList aus den Brotkrümeln der Seite.
  • Der Schema-Normalisierer (templates/src/lib/schema.ts).
  • Crawler: robots offen für die KI-Crawler, die pages.dev-Builds auf noindex gesetzt, und eine Sitemap mit echten lastmods.
• 4. Seiten: Struktur, eingebaut; Wörter, vorgeschlagen. Seiten-Agenten korrigieren die Überschriften-Reihenfolge, machen jeden Abschnitt eigenständig und rendern Text als Text (references/page-brief.md, „Such- und Antwort-Engines“). Formulierungsideen kommen als Vorschläge zu dir zurück.
• 6. CMS: Aktualität und Item-Schema.
  • Daten: datePublished und dateModified aus dem CMS.
  • Beiträge: Article/BlogPosting, mit dem Autor.
  • Listen: CollectionPage mit einer ItemList.
  • Zahlen: alles, was die Seite zeigt, ist zur Build-Zeit im HTML, nicht im Browser abgerufen.
• 7. Assets: Geschwindigkeit und Bedeutung.
  • LCP und Lazy Video: ein schneller Hero, mit Videos unterhalb des Falzes, die lazy geladen werden.
  • Alt-Text, der sagt, was das Bild zeigt.
  • Video, das Inhalt transportiert (eine Demo, ein Vortrag) erhält VideoObject.
• 8. Parität: das vollständige Audit, auf pages.dev. Führe die Checkliste erneut auf dem Neubau aus. Alles, was noch offen in docs/seo.md ist, geht als eine Liste von Vorschlägen an den Besitzer.
• 9. Weiterleitungen: behalte die Equity. Jede Weiterleitung ist ein einzelner Hop, und jede gelöschte oder zusammengeführte Seite geht zu ihrem nächstgelegenen Äquivalent.
• 11. Umschalten: sag es den Engines. Reiche die Sitemap in der Search Console und Bing erneut ein, aktiviere Crawler Hints (IndexNow) und beobachte die Abdeckung.
• 12. Rückgabe: messe, dann schau off-site.
  • Vergleiche mit der Basislinie.
  • Gib dem Besitzer den Off-Site-Plan des Skills: die zwei oder drei Kanäle, die KI-Engines für diese Kategorie am häufigsten zitieren. Die meisten Zitate kommen von Drittanbieter-Seiten, also kann die Seite allein sie nicht gewinnen.

seo-aeo-geo ist ein separates Skill (adamperlis/claude-skill-seo-aeo-geo). Wenn es nicht installiert ist, funktioniert der Umzug trotzdem: mache die Verbesserungen, die jeder oben genannte Punkt aus den eigenen Notizen dieses Skills benennt (Schritt 8s Audit-Liste, references/page-brief.md, references/site-types.md), schreibe die Geld-Prompts selbst (die Fragen, die das Publikum dieser Seite einer KI-Engine stellt), und sage dem Besitzer, dass das vollständige Audit und der Off-Site-Plan übersprungen wurden.

Die Schritte

1. Inventur (schreibgeschützt, ~15 Min)

Führe python3 -I scripts/inventory.py https://www.example.com > inventory.md aus. Es liest die Sitemap, Robots, jede Seite (Titel, Beschreibung, OG, Canonical, JSON-LD-Typen, noindex), CMS-Listen (w-dyn-list), Formulare, Drittanbieter-Hosts, GA/GTM/Pixel-IDs, Hintergrundvideos und deren Größen, und die Apex/www/MX/NS-Einträge. Dann, mit den Webflow-MCP-Tools, falls verbunden (data_sites_tool, data_cms_tool, data_forms_tool, data_webhook_tool):

• Collections: liste sie auf und zähle die Items in jeder (list_collection_items limit 1 → pagination.total).
• Formulare: liste sie auf, ignoriere Finsweet „Cookie Preferences“-Formulare (eines pro Seite × Domain).
• Weiterleitungen und HSTS: im Dashboard, Site settings → Publishing, exportiere die 301-Weiterleitungen als CSV und notiere „HSTS für Subdomains“.
• Suche und Eigentümerschaft: wie die Search Console verifiziert ist (Meta-Tag oder DNS-TXT), GA4/GTM (und alle GTM-Trigger, die auf Webflow-Markup aufbauen), Bing und andere Verifikations-Tags. Die Liste ist in references/inventory.md.
• Domains: der Registrar, Ablaufdatum, Transfer-Lock, DNSSEC und ob die Domain über Webflow gekauft wurde (references/domains.md).
• Seiten außerhalb der Sitemap: Webflow liefert Seiten aus, die die Sitemap auslässt. Finde sie, indem du die HTML-Dateien des Exports mit der Live-Sitemap differierst, dann curl jede einzelne.
  • Erfolgsseiten, wie ein Formular-Weiterleitungsziel, müssen übernommen werden.
  • Lasse Ecommerce-Vorlagen (/checkout, /order-confirmation) weg, wenn die Seite nicht verkauft, und Passwortseiten (401), wenn nichts geschützt ist.
• Was für eine Art von Seite es ist: wofür sie da ist, was ein Besucher dort tun soll (kaufen, buchen, spenden, abonnieren, Kontakt aufnehmen), und auf welche Webflow-Funktionen sie sich stützt (Ecommerce, Benutzerkonten, Lokalisierung, Passwortseiten, Datei-Uploads, RSS). references/site-types.md behandelt, was jeder Typ ändert: den Schema-Typ der Entität, die zu zählenden Conversions und die Funktionen, die einen eigenen Plan brauchen.

Lies references/inventory.md für die Bedeutung jedes Fundes und die Fragen an den Besitzer (Zapier-Zaps, wer bearbeitet Inhalte, Analytics, die nie funktioniert haben).

Notiere eine SEO-Basislinie, bevor sich etwas ändert (mit dem seo-aeo-geo-Skill):

• Search Console: exportiere die Performance der letzten 3 Monate (Top-Seiten und -Suchanfragen, plus KI-Übersichts-Impressionen, falls angezeigt) und die Anzahl der indexierten Seiten.
• Geld-Prompts: führe sie in ChatGPT, Perplexity und Gemini aus und notiere, ob die Seite zitiert wird. Dies sind die Fragen, die das Publikum dieser Seite stellt: Käufer, Essengeher, Spender, Leser oder Kunden.
  • Führe sie aus dem Land des Publikums aus. KI-Engines antworten nach Standort, also ist eine aus dem Ausland durchgeführte Ausführung nicht die Sicht des Publikums. Verwende bei Bedarf ein VPN in ihrem Land.
  • Notiere den Standort mit der Ausführung und verwende denselben für die Nachher-Hälfte.

Halte es in docs/move.md. Es ist die Vorher-Hälfte des Vergleichs in Schritt 12. Auditiere dann die Live-Seite mit demselben Skill, in docs/seo.md (siehe „seo-aeo-geo auf dem Weg“).

2. Backup: Export + Spiegel

• Code-Export (Designer → ☰ → Export code → Prepare ZIP → Download). Frage den Besitzer vor dem Herunterladen.
  • Entpacke mit python3 -I scripts/unzip_webflow.py (es repariert die Nicht-UTF-8-Dateinamen, die unzip mit „disk full?“ zum Scheitern bringen).
  • MISSING.txt listet Videos auf, die nicht exportiert wurden; der Spiegel holt sie vom CDN.
• Spiegele die Live-Seite: python3 -I scripts/mirror.py https://www.example.com reference/ speichert das HTML jeder Seite in reference/live/ und jede Datei auf Webflows CDNs in reference/assets/<kind>/, mit einem Manifest. Committe reference/live/ (die Aufzeichnung dessen, was live war); git-ignore reference/assets/.
• Screenshots: node scripts/shots.mjs https://www.example.com live (Desktop 1440 und Telefon 390). Webflow-Interaktionen verstecken Elemente, bis sie in den Viewport scrollen, also sind leere Bereiche in ganzseitigen Aufnahmen normalerweise nicht aufgedeckte Inhalte: lies das HTML.

3. Gerüst erstellen (du, vor jeder Seitenarbeit)

Kopiere templates/ in das neue Repo (templates/README.md zeigt jede Datei).

• Konfiguration: astro.config.mjs verwendet build.format: 'file' und trailingSlash: 'never', weil Webflow-URLs keinen abschließenden Schrägstrich haben. Die Entwickler-Symbolleiste ist aus, damit Screenshots übereinstimmen.

• Tokens: nimm sie aus dem Designsystem des Besitzers, falls vorhanden; verwende andernfalls die Webflow-CSS-:root-Variablen und Typ-Skalierung.

• Gemeinsame Teile: Layout (Head-Parität, Analytics nur auf dem Produktions-Hostnamen), Nav, Footer, die CTA-Blöcke, die sich Seiten teilen, das Lazy-BgVideo und Bewegung (Einblendungen mit einer Ausfallsicherung).

• Die Suchebene, von Anfang an:

  • Landmarks im Layout.
  • Die Entität, einmal definiert (src/data/entity.ts, mit Fakten vom Besitzer, nicht aus den alten Seiten abgeleitet).
  • Den JSON-LD-Normalisierer, durch den das Schema jeder Seite läuft.
  • Crawler und Sitemap: robots offen für die KI-Crawler, noindex auf den pages.dev-Builds und echte lastmods in der Sitemap.

  Seiten, die auf diesem Gerüst gebaut werden, erben alles.

• Messe zuerst: nimm Live-Größen mit scripts/measure.mjs und baue die gemeinsamen Teile darauf.

Webflow-Verhaltensweisen, über die zu entscheiden ist:

• Seitenübergänge: viele Webflow-Seiten haben eine Abdeckung (.transition + .transition-trigger + ein jQuery-Snippet, das den Trigger beim Laden und erneut bei jedem internen Link klickt, dann window.location nach ~1s setzt). Besitzer bemerken, wenn sie fehlt, und verlangen sie zurück. Baue sie auf beide Arten in einfachem CSS + JS, aus unter reduced motion:
  • Ankunft: die Abdeckung hält, hebt sich dann weg, mit den Verzögerungen und Easing der Live-Version (aus den IX2-Aktionslisten im exportierten webflow.js).
  • Verlassen: ein Klick auf einen Link derselben Seite (nicht #, kein neuer Tab, kein modifizierter Klick) bringt die Abdeckung über die Seite und navigiert erst dann. Lies die IX2-Verzögerungen. Ein Slide-In, das 2s wartet, während das Snippet nach 1s geht, zeigt auf der Live-Seite nur eine tote Pause. Baue, was gemeint war (die Abdeckung in etwa 0,8s herunter), nicht die Pause.
  • Zurück: bei pageshow mit persisted, entferne die Abdeckung, sonst kommt die Seite aus dem Verlaufscache abgedeckt zurück.
  • Wo es angezeigt wird: überprüfe das berechnete display auf Live bei 375 und 1440 (scripts/measure.mjs), nicht das CSS. Ein benutzerdefinierter Embed (body .transition { display: block }) kann das eigene display: none der Seite bei ≤767px überschreiben, also wird es auch auf Telefonen angezeigt.
• Finsweet-Einwilligung: mit Consent Mode v2 schiebe auch Finsweets eigene dataLayer-Ereignisse (<category>-activated). GTM-Trigger, die für Finsweet gebaut wurden, feuern dann weiter.

Zwei CSS-Fallen, die Stunden kosten:

• Basisgröße auf body: setze Webflows 10px-Basisschriftgröße auf body, niemals auf html. Auf html wird 1rem zu 10px und jede Tailwind-Spacing- und -Größe rendert bei 62,5 %.
• Keine gemischten Breakpoints: mische keine rem-Breakpoints (md:, lg:) mit px-Breakpoints (min-[992px]:) für dieselbe Eigenschaft in einer Datei; Tailwind 4 kann sie falsch anordnen. Verwende eine Art pro Komponente.

4. Seiten: parallel, ein Agent pro Seitengruppe

Gib jedem Agenten references/page-brief.md (füge den Repo-Pfad, Port, gemeinsame Komponenten, Tokens ein) plus die Route, Head-Werte und Abschnittsliste seiner Seite.