Was macht share-cards?
Vorschaucrawler (Chat-Apps, soziale Netzwerke, Suchmaschinen) lesen das HTML, das ein Server ausliefert, und führen kein JavaScript aus. Eine Single-Page-App sendet für jede Adresse dasselbe HTML, daher zeigt jeder Link dieselbe Vorschau. share-cards behebt beide Probleme:
- Rendern: eine HTML-Vorlage + eine Liste von Seiten → ein 1200×630 JPEG pro Seite, gezeichnet in einem Headless-Browser.
- Inject: das gebaute
index.html→ eine HTML-Datei pro Seite, jede mit eigenem<title>, Beschreibung, kanonischer URL,og:*- undtwitter:*-Tags.
Skill-Ordner: ~/.claude/skills/share-cards/ (im Folgenden als $S bezeichnet). Jeder Befehl ist $S/cards <command> [dir], wobei [dir] die cards.config.json enthält. $S/cards help listet alle Befehle auf.
$S/cards die Kommandozeile
$S/lib/ Konfiguration, Tag-Injektion, Rendering, Verifikation, Vorschau, Rewrites
$S/templates/ editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs führt inject nach `vite build` aus
$S/references/templates.md Slots, Variablen und Anleitung für eigene Vorlagen
$S/examples/site/ eine 4-Seiten-Beispielseite mit Karten und injizierten Seiten
$S/README.md Konfigurationsreferenz, Framework-Hinweise, Grenzen
Arbeitsablauf
- Maschine prüfen:
$S/cards check. Nurrenderundpreviewbenötigen einen Browser. - Seiten finden: Lies den Router oder den Inhaltsordner des Projekts und liste jede öffentliche Adresse auf. Finde, wo statische Dateien ausgeliefert werden (
public/,static/) und wohin der Build geht (dist/,build/,out/). - Gerüst erstellen:
$S/cards init <project>(--mjshinzufügen, wenn die Seitenliste aus den eigenen Routen oder Inhaltsdaten des Projekts gebaut werden soll, damit sie nicht auseinanderdriftet). SetzesiteUrl(die echtehttps://-Origin),siteName,imageDir(innerhalb des statischen Ordners, z. B.public/og),imageUrlPath(wo dieser Ordner ausgeliefert wird, z. B./og) unddist. - Jeder Seiteneintrag schreiben:
title: der vollständige Seitentitel, wie er in der Vorschau erscheinen soll.description: ein Satz, maximal 160 Zeichen.cardTitle: die Wörter, die auf der Karte gezeichnet werden. Kurz halten (ca. 2 bis 6 Wörter). Mit*Sternchen*markierte Wörter werden in der Akzentfarbe gezeichnet.cardDescription(optional, eine kürzere Zeile für die Karte),kicker(kleines Label),art(eine Bilddatei aus dem Projekt),template(seitenweise Überschreibung).- Erfinde niemals Fakten, Zahlen oder Zitate für diese Felder. Übernimm die Wörter aus der Seite selbst.
- Vorlage und Design wählen:
editorial(Papier, schweres Serif),minimal(weiß, ruhig),technical(dunkel, Monospace). Setzethemeauf die eigenen Farben des Projekts. Für alles andere führe$S/cards eject <name> card.htmlaus, bearbeite es und setze"template": "./card.html". Siehereferences/templates.md. - Rendern:
$S/cards render <project>. Lies jede Warnung: Ein abgeschnittener Titel oder Beschreibung bedeutet, dass der Text gekürzt werden muss. - Ergebnis ansehen:
$S/cards preview <project>schreibtcards-preview/contact-sheet.pngundchat-preview.png. Lies beide PNGs. Prüfe jede Karte auf abgeschnittene Wörter, Überfüllung, schwachen Kontrast und versteckte Bilder. Korrigiere und rendere erneut. Sage dem Benutzer nicht, dass die Karten richtig aussehen, bevor du sie überprüft hast. - Seitengerüst vorbereiten:
injectfüllt Tags, die bereits vorhanden sind, und schlägt fehl, wenn eines fehlt. Führe$S/cards tags <project>aus und füge den Block in den<head>der Quell-index.htmlein, wobei alte Share-Tags ersetzt werden (oder--add-missingverwenden). - In den Build einbinden:
- Vite: füge
shareCards()aus$S/vite-plugin.mjszupluginshinzu (siehe README). - Alles andere: führe
$S/cards inject <project>nach dem Build-Befehl aus.
- Vite: füge
- Host-Regeln: Wenn der Host einen Catch-All-Rewrite auf
/index.htmlhat, drucke Seitenregeln mit$S/cards rewrites vercel|netlify|netlify-toml <project>und platziere sie vor dem Catch-All. Zeige dem Benutzer die Regeln; bearbeite die Host-Konfiguration nicht ohne Ansage. - Verifizieren: Baue die Seite, dann
$S/cards verify <project>. Es muss mitAll good.enden. - Dem Benutzer mitteilen, was noch zu tun ist: Deployen, dann einen echten Link in eine Chat-App einfügen. Vorschauen werden von jeder App zwischengespeichert, manchmal tagelang; setze
"versionImages": true, um die Bildadresse bei jeder Änderung einer Karte zu ändern.
Regeln
siteUrlmuss die Produktions-Origin sein. Vorschaubilder benötigen absolutehttps://-Adressen.- Rendere Karten vor dem Build, damit der Build sie kopiert, und committe die Karten sowie
cards.lock.json. CI benötigt dann keinen Browser. - Während des Renderns wird nichts aus dem Netzwerk geholt, es sei denn, die Konfiguration setzt
"allowNetwork": true. Web-Schriftarten müssen lokale Dateien sein, die unterfontsaufgelistet sind. - Schriftarten verwenden standardmäßig System-Stapel, sodass auf anderen Maschinen gezeichnete Karten abweichen können. Für identische Ausgabe überall füge Schriftartdateien zum Projekt hinzu (überprüfe die Lizenz) und liste sie unter
fontsauf. - Sage klar, was nicht überprüft wurde: der echte Crawler jeder App und die Routing-Konfiguration des Hosts nach dem Deploy.