CommunityImagegithub.com

share-cards

Générez des images de prévisualisation Open Graph (1200x630) pour chaque page d'un site à partir d'un modèle HTML unique, et injectez les balises méta appropriées dans chaque page au moment du build, pour que les liens partagés dans les applications de chat et les réseaux sociaux affichent la bonne prévisualisation.

Qu'est-ce que share-cards ?

share-cards est un outil en ligne de commande conçu pour résoudre un problème courant des applications monopages (SPA) : les crawlers de prévisualisation (applications de chat, réseaux sociaux, moteurs de recherche) ne lisent que le HTML statique envoyé par le serveur, sans exécuter JavaScript. Par conséquent, une SPA renvoie le même HTML pour toutes ses routes, ce qui entraîne la même prévisualisation pour tous les liens, ou pire, aucune prévisualisation. share-cards agit en deux étapes. D'abord, il utilise un navigateur headless pour générer une image JPEG de 1200x630 pixels pour chaque page, à partir d'un modèle HTML unique et d'une liste de pages. Ensuite, il injecte dans le fichier `index.html` compilé les balises `<title>`, `description`, `canonical`, `og:*` et `twitter:*` propres à chaque page, créant ainsi un fichier HTML distinct pour chaque adresse publique. L'outil est livré avec trois modèles prêts à l'emploi (`editorial`, `minimal`, `technical`) et des mécanismes permettant de personnaliser les polices, les couleurs et les images. Il intègre également des vérifications de qualité, comme la génération d'une planche contact et d'une prévisualisation dans un chat. Le workflow complet comprend la vérification de l'environnement, la découverte des pages, le scaffold, l'écriture des entrées, le rendu, la prévisualisation, l'injection des balises, l'intégration au build (avec un plugin Vite dédié) et une vérification finale. L'outil assure que les images sont générées avant le build pour éviter de devoir exécuter un navigateur dans l'intégration continue, et il gère les règles de routage pour les hébergeurs comme Vercel et Netlify afin que les crawlers trouvent la bonne page HTML.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/share-cards/tree/HEAD

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. rendu : un modèle HTML + une liste de pages → une image JPEG de 1200x630 par page, dessinée dans un navigateur headless.
  2. injection : le index.html compilé → un fichier HTML par page, chacun avec ses propres balises <title>, description, canonical, og:* et twitter:*.

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

  1. Vérifier la machine : $S/cards check. Seuls render et preview ont besoin d'un navigateur.
  2. 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/).
  3. Scaffold : $S/cards init <projet> (ajoutez --mjs lorsque 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éfinissez siteUrl (l'origine https:// réelle), siteName, imageDir (dans le dossier statique, par ex. public/og), imageUrlPath (où ce dossier est servi, par ex. /og) et dist.
  4. É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.
  5. Choisir un modèle et un thème. editorial (papier, empattement lourd), minimal (blanc, discret), technical (sombre, monospace). Définissez theme avec 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". Voir references/templates.md.
  6. Rendu : $S/cards render <projet>. Lisez chaque avertissement : un titre ou une description tronqué signifie que le texte doit être raccourci.
  7. Regarder le résultat. $S/cards preview <projet> écrit cards-preview/contact-sheet.png et chat-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.
  8. Préparer la coquille de la page. inject remplit 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> du index.html source, en remplaçant les anciennes balises de partage (ou passez --add-missing).
  9. 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.
  10. 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.
  11. Vérifier : construisez le site, puis $S/cards verify <projet>. Cela doit se terminer par Tout est bon.
  12. 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": true pour changer l'adresse de l'image à chaque modification de carte.

Règles

  • siteUrl doit être l'origine de production. Les images de prévisualisation ont besoin d'adresses https:// 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 sous fonts.
  • 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é.

Skills associés