CommunityImagengithub.com

share-cards

Genera imágenes de vista previa de enlaces (tarjetas Open Graph de 1200x630 píxeles) para cada página de un sitio web a partir de una plantilla HTML, e inyecta el título, la descripción, la dirección canónica y las etiquetas de imagen propias de cada página en su HTML durante la compilación. Ideal para que las aplicaciones de una sola página muestren la vista previa correcta al compartir enlaces en aplicaciones de chat y redes sociales.

¿Qué es share-cards?

share-cards resuelve el problema de las vistas previas de enlaces incorrectas o genéricas en aplicaciones de una sola página (SPA) y sitios web dinámicos. Los rastreadores de vista previa (como los de aplicaciones de chat y redes sociales) no ejecutan JavaScript, por lo que una SPA que envía el mismo HTML para todas las rutas muestra siempre la misma vista previa. share-cards aborda esto en dos pasos: 1. **Renderizado**: Toma una plantilla HTML y una lista de páginas, y genera una imagen JPEG de 1200x630 píxeles por página utilizando un navegador headless. 2. **Inyección**: Modifica el archivo `index.html` compilado para crear un archivo HTML por página, cada uno con sus propias etiquetas `<title>`, meta description, canonical, og:* y twitter:*. La herramienta es compatible con Vite (a través de un plugin) y con cualquier otro sistema de compilación. Incluye pasos para verificar visualmente las tarjetas renderizadas, verificar la configuración del host (Vercel, Netlify) y validar que todo funcione correctamente. Es ideal para desarrolladores que necesitan que los enlaces de su SPA se vean bien al compartirse en Slack, Twitter, WhatsApp, etc. La habilidad se invoca mediante el comando `$S/cards` (por ejemplo, `$S/cards render <proyecto>`, `$S/cards inject <proyecto>`). El flujo de trabajo incluye verificar el entorno, definir páginas, elegir plantillas y temas, renderizar, previsualizar, inyectar etiquetas, integrar en la compilación y verificar el resultado final.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace share-cards?

Los rastreadores de vista previa (aplicaciones de chat, redes sociales, buscadores) leen el HTML que envía un servidor y no ejecutan JavaScript. Una aplicación de una sola página envía el mismo HTML para cada dirección, por lo que cada enlace muestra la misma vista previa. share-cards soluciona ambas partes:

  1. renderizado: una plantilla HTML + una lista de páginas → un JPEG de 1200x630 por página, dibujado en un navegador headless.
  2. inyección: el index.html compilado → un archivo HTML por página, cada uno con su propio <title>, descripción, canonical, etiquetas og:* y twitter:*.

Carpeta de la habilidad: ~/.claude/skills/share-cards/ (escrito a continuación como $S). Cada comando es $S/cards <comando> [directorio], donde [directorio] contiene cards.config.json. $S/cards help los lista.

$S/cards                    la línea de comandos
$S/lib/                     configuración, inyección de etiquetas, renderizado, verificación, vista previa, reescrituras
$S/templates/               editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs          ejecuta inject después de `vite build`
$S/references/templates.md  espacios, variables y cómo escribir tu propia plantilla
$S/examples/site/           un ejemplo de 4 páginas con sus tarjetas y páginas inyectadas
$S/README.md                referencia de configuración, notas sobre frameworks, límites

Flujo de trabajo

  1. Verifica la máquina: $S/cards check. Solo render y preview necesitan un navegador.
  2. Encuentra las páginas. Lee el enrutador del proyecto o la carpeta de contenido y lista cada dirección pública. Encuentra dónde se sirven los archivos estáticos (public/, static/) y hacia dónde va la compilación (dist/, build/, out/).
  3. Andamio: $S/cards init <proyecto> (agrega --mjs cuando la lista de páginas deba construirse a partir de los datos de ruta o contenido del propio proyecto, para que no pueda desviarse). Establece siteUrl (el origen real https://), siteName, imageDir (dentro de la carpeta estática, p. ej. public/og), imageUrlPath (dónde se sirve esa carpeta, p. ej. /og) y dist.
  4. Escribe la entrada de cada página:
    • title: el título completo de la página tal como debe aparecer en la vista previa.
    • description: una oración, de 160 caracteres como máximo.
    • cardTitle: las palabras dibujadas en la tarjeta. Mantenlo breve (de 2 a 6 palabras aproximadamente). *palabras* marcan palabras dibujadas en el color de acento.
    • cardDescription (opcional, una línea más corta para la tarjeta), kicker (etiqueta pequeña), art (un archivo de imagen del proyecto), template (anulación por página).
    • Nunca inventes hechos, números ni citas para estos valores. Toma las palabras de la propia página.
  5. Elige una plantilla y un tema. editorial (papel, serifa pesada), minimal (blanco, tranquilo), technical (oscuro, monoespaciado). Establece theme con los colores del propio proyecto. Para cualquier otra cosa, ejecuta $S/cards eject <nombre> card.html, edítalo y establece "template": "./card.html". Consulta references/templates.md.
  6. Renderiza: $S/cards render <proyecto>. Lee cada advertencia: un título o descripción cortados significa que el texto debe acortarse.
  7. Observa el resultado. $S/cards preview <proyecto> escribe cards-preview/contact-sheet.png y chat-preview.png. Lee ambos PNG. Verifica cada tarjeta en busca de palabras cortadas, aglomeración, contraste débil y arte que oculte el texto. Corrige y renderiza de nuevo. No le digas al usuario que las tarjetas se ven bien a menos que las hayas revisado.
  8. Prepara el shell de la página. inject completa las etiquetas que ya existen y falla si falta alguna. Ejecuta $S/cards tags <proyecto> y pega el bloque en el <head> del index.html fuente, reemplazando las etiquetas de compartir antiguas (o pasa --add-missing).
  9. Conéctalo a la compilación:
    • Vite: agrega shareCards() desde $S/vite-plugin.mjs a plugins (consulta el README).
    • Cualquier otra cosa: ejecuta $S/cards inject <proyecto> después del comando de compilación.
  10. Reglas del host: si el host tiene una reescritura global a /index.html, imprime las reglas de página con $S/cards rewrites vercel|netlify|netlify-toml <proyecto> y colócalas antes de la regla global. Muéstrale las reglas al usuario; no edites la configuración del host sin decirlo.
  11. Verifica: compila el sitio, luego ejecuta $S/cards verify <proyecto>. Debe terminar con Todo correcto.
  12. Dile al usuario qué queda: desplegar, luego pegar un enlace real en una aplicación de chat. Las vistas previas se almacenan en caché por cada aplicación, a veces durante días; establece "versionImages": true para cambiar la dirección de la imagen cada vez que una tarjeta cambie.

Reglas

  • siteUrl debe ser el origen de producción. Las imágenes de vista previa necesitan direcciones https:// absolutas.
  • Renderiza las tarjetas antes de la compilación para que la compilación las copie, y confirma las tarjetas y cards.lock.json. CI entonces no necesita navegador.
  • No se obtiene nada de la red durante el renderizado a menos que la configuración establezca "allowNetwork": true. Las fuentes web deben ser archivos locales listados bajo fonts.
  • Las fuentes por defecto son las pilas del sistema, por lo que las tarjetas dibujadas en otra máquina pueden diferir. Para una salida idéntica en todas partes, agrega archivos de fuente al proyecto (verifica su licencia) y listalos bajo fonts.
  • Di claramente lo que no se verificó: el rastreador real de cada aplicación y el enrutamiento del host una vez desplegado.

Skills relacionados