Que fait share-cards ?
Les crawlers de prévisualisation (applications de chat, réseaux sociaux, moteurs de recherche) lisent le HTML envoyé par un serveur et n'exécutent pas JavaScript. Une application monopage envoie le même HTML pour chaque adresse, donc chaque lien affiche la même prévisualisation. share-cards résout ces deux problèmes :
- rendu : un modèle HTML + une liste de pages → une image JPEG de 1200x630 par page, dessinée dans un navigateur headless.
- injection : le
index.htmlcompilé → un fichier HTML par page, chacun avec ses propres balises<title>,description,canonical,og:*ettwitter:*.
Dossier de la compétence : ~/.claude/skills/share-cards/ (écrit ci-dessous comme $S). Chaque commande est $S/cards <commande> [dossier], où [dossier] contient cards.config.json. $S/cards help les liste.
$S/cards la ligne de commande
$S/lib/ configuration, injection de balises, rendu, vérification, prévisualisation, réécritures
$S/templates/ editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs exécute l'injection après `vite build`
$S/references/templates.md emplacements, variables et comment écrire votre propre modèle
$S/examples/site/ un site d'exemple de 4 pages avec ses cartes et pages injectées
$S/README.md référence de configuration, notes sur les frameworks, limites
Flux de travail
- Vérifier la machine :
$S/cards check. Seulsrenderetpreviewont besoin d'un navigateur. - Trouver les pages. Lisez le routeur du projet ou le dossier de contenu et listez chaque adresse publique. Trouvez où les fichiers statiques sont servis (
public/,static/) et où le build est produit (dist/,build/,out/). - Scaffold :
$S/cards init <projet>(ajoutez--mjslorsque la liste des pages doit être construite à partir des propres données de route ou de contenu du projet, afin qu'elle ne puisse pas dériver). DéfinissezsiteUrl(l'originehttps://réelle),siteName,imageDir(dans le dossier statique, par ex.public/og),imageUrlPath(où ce dossier est servi, par ex./og) etdist. - Écrire l'entrée de chaque page :
title: le titre complet de la page tel qu'il doit apparaître dans la prévisualisation.description: une phrase, 160 caractères au maximum.cardTitle: les mots dessinés sur la carte. Gardez-le court (environ 2 à 6 mots).*astérisques*marquent les mots dessinés dans la couleur d'accentuation.cardDescription(optionnel, une ligne plus courte pour la carte),kicker(petite étiquette),art(un fichier image du projet),template(remplacement par page).- N'inventez jamais de faits, de chiffres ou de citations pour ceux-ci. Prenez les mots de la page elle-même.
- Choisir un modèle et un thème.
editorial(papier, empattement lourd),minimal(blanc, discret),technical(sombre, monospace). Définissezthemeavec les propres couleurs du projet. Pour tout autre chose, exécutez$S/cards eject <nom> card.html, modifiez-le et définissez"template" : "./card.html". Voirreferences/templates.md. - Rendu :
$S/cards render <projet>. Lisez chaque avertissement : un titre ou une description tronqué signifie que le texte doit être raccourci. - Regarder le résultat.
$S/cards preview <projet>écritcards-preview/contact-sheet.pngetchat-preview.png. Lisez les deux PNG. Vérifiez chaque carte pour les mots coupés, le tassement, le faible contraste et l'art qui cache le texte. Corrigez et refaites le rendu. Ne dites pas à l'utilisateur que les cartes sont correctes à moins que vous ne les ayez regardées. - Préparer la coquille de la page.
injectremplit les balises qui existent déjà et échoue s'il en manque une. Exécutez$S/cards tags <projet>et collez le bloc dans le<head>duindex.htmlsource, en remplaçant les anciennes balises de partage (ou passez--add-missing). - Intégrer au build :
- Vite : ajoutez
shareCards()depuis$S/vite-plugin.mjsàplugins(voir README). - Autre chose : exécutez
$S/cards inject <projet>après la commande de build.
- Vite : ajoutez
- Règles d'hébergement : si l'hôte a une réécriture générique vers
/index.html, affichez les règles par page avec$S/cards rewrites vercel|netlify|netlify-toml <projet>et placez-les avant la règle générique. Montrez les règles à l'utilisateur ; ne modifiez pas la configuration de l'hôte sans le dire. - Vérifier : construisez le site, puis
$S/cards verify <projet>. Cela doit se terminer parTout est bon. - Dire à l'utilisateur ce qu'il reste : déployer, puis coller un lien réel dans une application de chat. Les prévisualisations sont mises en cache par chaque application, parfois pendant des jours ; définissez
"versionImages": truepour changer l'adresse de l'image à chaque modification de carte.
Règles
siteUrldoit être l'origine de production. Les images de prévisualisation ont besoin d'adresseshttps://absolues.- Faites le rendu des cartes avant le build afin que le build les copie, et validez les cartes et
cards.lock.json. Le CI n'aura alors besoin d'aucun navigateur. - Rien n'est récupéré depuis le réseau pendant le rendu, sauf si la configuration définit
"allowNetwork": true. Les polices web doivent être des fichiers locaux listés sousfonts. - Les polices par défaut sont les piles système, donc les cartes dessinées sur une autre machine peuvent différer. Pour une sortie identique partout, ajoutez des fichiers de police au projet (vérifiez leur licence) et listez-les sous
fonts. - Dites clairement ce qui n'a pas été vérifié : le vrai robot d'exploration de chaque application et le routage de l'hôte une fois déployé.