¿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:
- renderizado: una plantilla HTML + una lista de páginas → un JPEG de 1200x630 por página, dibujado en un navegador headless.
- inyección: el
index.htmlcompilado → un archivo HTML por página, cada uno con su propio<title>, descripción, canonical, etiquetasog:*ytwitter:*.
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
- Verifica la máquina:
$S/cards check. Solorenderypreviewnecesitan un navegador. - 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/). - Andamio:
$S/cards init <proyecto>(agrega--mjscuando la lista de páginas deba construirse a partir de los datos de ruta o contenido del propio proyecto, para que no pueda desviarse). EstablecesiteUrl(el origen realhttps://),siteName,imageDir(dentro de la carpeta estática, p. ej.public/og),imageUrlPath(dónde se sirve esa carpeta, p. ej./og) ydist. - 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.
- Elige una plantilla y un tema.
editorial(papel, serifa pesada),minimal(blanco, tranquilo),technical(oscuro, monoespaciado). Establecethemecon los colores del propio proyecto. Para cualquier otra cosa, ejecuta$S/cards eject <nombre> card.html, edítalo y establece"template": "./card.html". Consultareferences/templates.md. - Renderiza:
$S/cards render <proyecto>. Lee cada advertencia: un título o descripción cortados significa que el texto debe acortarse. - Observa el resultado.
$S/cards preview <proyecto>escribecards-preview/contact-sheet.pngychat-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. - Prepara el shell de la página.
injectcompleta las etiquetas que ya existen y falla si falta alguna. Ejecuta$S/cards tags <proyecto>y pega el bloque en el<head>delindex.htmlfuente, reemplazando las etiquetas de compartir antiguas (o pasa--add-missing). - Conéctalo a la compilación:
- Vite: agrega
shareCards()desde$S/vite-plugin.mjsaplugins(consulta el README). - Cualquier otra cosa: ejecuta
$S/cards inject <proyecto>después del comando de compilación.
- Vite: agrega
- 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. - Verifica: compila el sitio, luego ejecuta
$S/cards verify <proyecto>. Debe terminar conTodo correcto. - 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": truepara cambiar la dirección de la imagen cada vez que una tarjeta cambie.
Reglas
siteUrldebe ser el origen de producción. Las imágenes de vista previa necesitan direccioneshttps://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 bajofonts. - 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.