CommunityImagemgithub.com

share-cards

Gera imagens de pré-visualização de links (cartões Open Graph de 1200x630) para cada página de um site a partir de um modelo HTML, e insere as tags de título, descrição, endereço canônico e imagem próprias de cada página no seu HTML durante a compilação, garantindo que links compartilhados em aplicativos de chat e redes sociais mostrem a pré-visualização correta, mesmo para aplicativos de página única.

O que é share-cards?

O **share-cards** resolve o problema comum de pré-visualização de links em aplicativos de página única (SPAs) e sites estáticos. Quando um link é compartilhado em aplicativos de chat como Slack ou WhatsApp, ou em redes sociais, esses serviços usam rastreadores que não executam JavaScript – eles leem apenas o HTML estático enviado pelo servidor. Como SPAs enviam o mesmo HTML para todas as rotas, todo link compartilhado mostra a mesma pré-visualização (geralmente a da página inicial), ou nenhuma. O share-cards ataca esse problema de duas formas: (1) **renderização**: a partir de um único modelo HTML e uma lista de páginas, ele gera uma imagem JPEG de 1200×630 pixels para cada página, usando um navegador headless; (2) **injeção**: durante a compilação, ele cria um arquivo HTML individual para cada página, cada um com seu próprio título, descrição, URL canônica e tags Open Graph e Twitter Cards. A ferramenta é executada via linha de comando (`$S/cards`) e inclui verificações de ambiente, geração de cartões, pré-visualização de resultados (gerando uma folha de contato e uma simulação de chat), injeção de tags no HTML, e suporte a plugins para Vite. É ideal para desenvolvedores que querem garantir que links compartilhados de seus projetos (SPAs, sites estáticos, blogs) mostrem pré-visualizações ricas e corretas, independentemente do framework ou plataforma de hospedagem.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que share-cards faz?

Os rastreadores de pré-visualização (aplicativos de chat, redes sociais, buscadores) leem o HTML que um servidor envia e não executam JavaScript. Um aplicativo de página única envia o mesmo HTML para todo endereço, então todo link mostra a mesma pré-visualização. share-cards corrige ambas as metades:

  1. renderização: um modelo HTML + uma lista de páginas → um JPEG de 1200×630 por página, desenhado em um navegador headless.
  2. injeção: o index.html compilado → um arquivo HTML por página, cada um com seu próprio <title>, descrição, canônico, tags og:* e twitter:*.

Pasta da habilidade: ~/.claude/skills/share-cards/ (escrita abaixo como $S). Todo comando é $S/cards <comando> [dir], onde [dir] contém cards.config.json. $S/cards help lista os comandos.

$S/cards                    a linha de comando
$S/lib/                     configuração, injeção de tags, renderização, verificação, pré-visualização, regras de reescrita
$S/templates/               editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs          executa inject após `vite build`
$S/references/templates.md  slots, variáveis e como escrever seu próprio modelo
$S/examples/site/           um site de exemplo com 4 páginas e suas páginas injetadas
$S/README.md                referência de configuração, notas sobre frameworks, limites

Fluxo de trabalho

  1. Verifique a máquina: $S/cards check. Apenas render e preview precisam de um navegador.
  2. Encontre as páginas. Leia o roteador do projeto ou a pasta de conteúdo e liste todo endereço público. Descubra de onde os arquivos estáticos são servidos (public/, static/) e para onde vai a compilação (dist/, build/, out/).
  3. Estrutura inicial: $S/cards init <projeto> (adicione --mjs quando a lista de páginas deve ser construída a partir dos dados de rota ou conteúdo do próprio projeto, para que não haja divergência). Defina siteUrl (a origem https:// real), siteName, imageDir (dentro da pasta estática, ex. public/og), imageUrlPath (onde essa pasta é servida, ex. /og) e dist.
  4. Escreva a entrada de cada página:
    • title: o título completo da página como deve aparecer na pré-visualização.
    • description: uma frase, no máximo 160 caracteres.
    • cardTitle: as palavras desenhadas no cartão. Mantenha curto (cerca de 2 a 6 palavras). *estrelas* marcam palavras desenhadas na cor de destaque.
    • cardDescription (opcional, uma linha mais curta para o cartão), kicker (pequeno rótulo), art (um arquivo de imagem do projeto), template (substituição por página).
    • Nunca invente fatos, números ou citações para esses campos. Extraia as palavras da própria página.
  5. Escolha um modelo e tema. editorial (papel, serifa pesada), minimal (branco, discreto), technical (escuro, monoespaçado). Defina theme com as cores do próprio projeto. Para qualquer outra coisa, execute $S/cards eject <nome> card.html, edite-o e defina "template": "./card.html". Veja references/templates.md.
  6. Renderize: $S/cards render <projeto>. Leia cada aviso: um título ou descrição cortados significam que o texto deve ser encurtado.
  7. Veja o resultado. $S/cards preview <projeto> escreve cards-preview/contact-sheet.png e chat-preview.png. Leia ambos os PNGs. Verifique cada cartão quanto a palavras cortadas, aglomeração, contraste fraco e arte que esconde o texto. Corrija e renderize novamente. Não diga ao usuário que os cartões estão corretos a menos que você tenha verificado.
  8. Prepare o shell da página. inject preenche tags que já existem e falha se alguma estiver faltando. Execute $S/cards tags <projeto> e cole o bloco no <head> do index.html fonte, substituindo quaisquer tags de compartilhamento antigas (ou passe --add-missing).
  9. Conecte-o à compilação:
    • Vite: adicione shareCards() de $S/vite-plugin.mjs a plugins (veja README).
    • Qualquer outra coisa: execute $S/cards inject <projeto> após o comando de compilação.
  10. Regras de hospedagem: se o host tiver uma regra de reescrita genérica para /index.html, imprima as regras de página com $S/cards rewrites vercel|netlify|netlify-toml <projeto> e coloque-as antes da regra genérica. Mostre as regras ao usuário; não edite a configuração do host sem avisar.
  11. Verifique: compile o site, depois $S/cards verify <projeto>. Deve terminar com All good.
  12. Diga ao usuário o que falta: implantar, depois cole um link real em um aplicativo de chat. As pré-visualizações são armazenadas em cache por cada aplicativo, às vezes por dias; defina "versionImages": true para alterar o endereço da imagem sempre que um cartão mudar.

Regras

  • siteUrl deve ser a origem de produção. Imagens de pré-visualização precisam de endereços https:// absolutos.
  • Renderize os cartões antes da compilação para que a compilação os copie, e faça commit dos cartões e de cards.lock.json. O CI então não precisa de navegador.
  • Nada é obtido da rede durante a renderização, a menos que a configuração defina "allowNetwork": true. Fontes da Web devem ser arquivos locais listados em fonts.
  • As fontes padrão são pilhas do sistema, então cartões desenhados em outra máquina podem diferir. Para saída idêntica em qualquer lugar, adicione arquivos de fonte ao projeto (verifique a licença) e liste-os em fonts.
  • Diga claramente o que não foi verificado: o rastreador real de cada aplicativo e o roteamento do host após a implantação.

Habilidades Relacionadas