Verificador de Meta Tags Open Graph e Compartilhamento Social

--- name: verificador-de-meta-tags-open-graph-e-de-compartilhamento-social description: Verifica o código-fonte HTML de uma página para as tags a partir das quais são construídas as prévisualizações de links - título e comprimento da descrição, rel=canonical, og:title/description/type/url/site_name/locale, og:image tamanho, proporção, alt e SVG, twitter:card e handles. Sinala URLs relativas/http://, parâmetros de rastreamento, duplicados de tema + plugin SEO, tags no <body> e placeholders {{ }} não renderizados, e devolve um bloco <head> corrigido. Inclui um verificador Python offline da stdlib com --self-test. --- # Verificador de Meta Tags Open Graph e de Compartilhamento Social Você faz que os links compartilhados tenham a aparência correta no Facebook, LinkedIn, X, Slack, Discord, WhatsApp e iMessage. Você lê o código-fonte da página que os rastreadores veem, mostra ao usuário a partir do que a prévisualização será construida (título, descrição, imagem, domínio), explica por que uma prévisualização está em branco, cortada ou mostrando o logo, e devolve um bloco `<head>` corrigido. Você trabalha a partir de HTML salvo; nunca afirma que obteve a página ao vivo ou que viu o cache de uma plataforma. ## Arquivos nesta skill - `scripts/og_meta_check.py` - analiza HTML com `html.parser` e verifica title, description, canonical, og:* e twitter:* tags; com `--root` lê a largura/altura real e o tamanho do arquivo de imagens de compartilhamento PNG/JPEG/GIF/WebP locais (só biblioteca padrão Python 3.8+) - `references/tag-rules.md` - cada tag, os valores que os rastreadores aceptam, comprimentos, tamanhos de imagem e fallbacks - `references/platform-notes.md` - como Facebook, LinkedIn, X, Slack, Discord, WhatsApp e iMessage constroem prévisualizações, as guardan em cache e como atualizarlas - `templates/share-meta-review.md` - a revisão a devolver (prévisualização, tabela de correções, bloco head corrigido, passos de atualização) - `examples/product-page.html` - uma página de produto cujo tema e plugin SEO ambos escreven tags, com erros de propósito - `examples/product-page-fixed.html` - a mesma página com um head correto (verificações limpias) - `examples/meta-report.md` - a saída real do verificador no exemplo com erros ## Fluxo de trabalho ### 1. Obter o HTML que os rastreadores veem Solicite a URL da página e o código-fonte renderizado pelo servidor, não a vista Elements do DevTools (essa mostra tags adicionadas por JavaScript, que a maioria dos rastreadores nunca executa): ``` curl -sL -A "facebookexternalhit/1.1" https://example.com/page -o page.html curl -sL -A "Twitterbot/1.0" https://example.com/page -o page-x.html ``` Para um site estático ou uma carpeta de build, apunte o verificador à carpeta e passe `--root` para que as imagens de compartilhamento sejam medidas desde o disco. Pregunte quais plataformas importan mais (B2B: LinkedIn e Slack; consumidor: WhatsApp, iMessage, Facebook, X). ### 2. Executar o verificador ``` python3 scripts/og_meta_check.py examples/product-page.html --url https://shop.example.com/shoes/trail-grip python3 scripts/og_meta_check.py dist/ --root dist/ --min-severity MEDIUM python3 scripts/og_meta_check.py page.html --url https://example.com/blog/post --json python3 scripts/og_meta_check.py --self-test ``` Dê `--url` para uma página única para que os links relativos sejam resolvidos e canonical/og:url comparados. Saída 0 = sem HIGH, 1 = achados HIGH, 2 = entrada inválida. Se não pode executar código, percorra `references/tag-rules.md` na mesma ordem. ### 3. Explicar a prévisualização - Comece com a tabela de prévisualização: isso é o que as pessoas verán. Uma `og:image` ausente, relativa ou SVG é a razão usual para um link de texto simples; uma imagem quadrada ou pequena obtiene uma miniatura pequena em lugar de um card grande. - **HIGH** rompe a prévisualização (sem og:image ou relativa, imagem menor de 200x200, sem título, vários canonicals). **MEDIUM** mostra a coisa errada (duplicados, placeholders, tags no `<body>`, twitter:card inválido, parâmetros de rastreamento, SVG). **LOW** é polimento (comprimentos, texto alternativo, formato de locale, site_name). - Duplicados geralmente vienen de dois sistemas (tema más plugin SEO, default do framework más componente de página). Diga qual desactivar em lugar de agregar um terceiro conjunto. ### 4. Entregar Preencha `templates/share-meta-review.md`: a prévisualização antes/después, a tabela de correções, um bloco `<head>` completo com valores reais (ou placeholders claramente marcados), a especificação da imagem de compartilhamento (1200x630 JPEG/PNG menor de ~1 MB, texto no centro seguro), e como atualizar caches (Facebook Sharing Debugger "Scrape Again", LinkedIn Post Inspector; X, Slack e WhatsApp re-obtienen después de que seu cache expire ou com uma URL cambiada). ## Resultado de exemplo En `examples/product-page.html` o verificador reporta 21 achados (HIGH 1, MEDIUM 10, LOW 10): a única og:image no `<head>` é um logo SVG relativo, a imagem real do produto está no `<body>` a 800x800, o plugin SEO agrega um segundo og:title com um `{{ product.name }}` não renderizado, og:url lleva `?utm_source=newsletter` e difiere do canonical relativo, `twitter:card` é `large`, twitter:site é uma URL em lugar de `@peakline`, og:description usa `name=` e corre 269 caracteres, e o título é só `Peakline`. `examples/product-page-fixed.html` verifica limpo (saída 0). ## Regras - Julgue o HTML renderizado pelo servidor; diga claramente quando as tags só existem después de que JavaScript é executado. - Nunca invente fatos do produto, precios ou handles de marca para as tags corrigidas; use o copy da própria página ou marque `<placeholder>`. - Um valor por tag de valor único; elimine a fonte duplicada em lugar de sobrescribirla. - Todas as URLs em og:url, og:image, twitter:image e canonical devem ser URLs absolutas https:// sem parâmetros de rastreamento. - Não prometa como uma plataforma vai cortar ou quando atualiza; dê os tamanhos documentados e a ferramenta de atualização, e marque o resto "a verificar" no debugger da plataforma. - Mantenga og:title livre do sufixo de nome de site (og:site_name lleva a marca) a menos que o usuário o queira.