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:
- renderização: um modelo HTML + uma lista de páginas → um JPEG de 1200×630 por página, desenhado em um navegador headless.
- injeção: o
index.htmlcompilado → um arquivo HTML por página, cada um com seu próprio<title>, descrição, canônico, tagsog:*etwitter:*.
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
- Verifique a máquina:
$S/cards check. Apenasrenderepreviewprecisam de um navegador. - 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/). - Estrutura inicial:
$S/cards init <projeto>(adicione--mjsquando 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). DefinasiteUrl(a origemhttps://real),siteName,imageDir(dentro da pasta estática, ex.public/og),imageUrlPath(onde essa pasta é servida, ex./og) edist. - 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.
- Escolha um modelo e tema.
editorial(papel, serifa pesada),minimal(branco, discreto),technical(escuro, monoespaçado). Definathemecom as cores do próprio projeto. Para qualquer outra coisa, execute$S/cards eject <nome> card.html, edite-o e defina"template": "./card.html". Vejareferences/templates.md. - Renderize:
$S/cards render <projeto>. Leia cada aviso: um título ou descrição cortados significam que o texto deve ser encurtado. - Veja o resultado.
$S/cards preview <projeto>escrevecards-preview/contact-sheet.pngechat-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. - Prepare o shell da página.
injectpreenche tags que já existem e falha se alguma estiver faltando. Execute$S/cards tags <projeto>e cole o bloco no<head>doindex.htmlfonte, substituindo quaisquer tags de compartilhamento antigas (ou passe--add-missing). - Conecte-o à compilação:
- Vite: adicione
shareCards()de$S/vite-plugin.mjsaplugins(veja README). - Qualquer outra coisa: execute
$S/cards inject <projeto>após o comando de compilação.
- Vite: adicione
- 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. - Verifique: compile o site, depois
$S/cards verify <projeto>. Deve terminar comAll good. - 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": truepara alterar o endereço da imagem sempre que um cartão mudar.
Regras
siteUrldeve ser a origem de produção. Imagens de pré-visualização precisam de endereçoshttps://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 emfonts. - 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.