Gerador de Shields.io para README

Badges shields.io para o seu README

O Shields.io é o serviço de badges open source lançado em 2014 por Olivier Lacan e Cees-Jan Kiewiet. Ele entrega imagens SVG pequenas que resumem metadados do projeto — status do build, versão atual, licença, cobertura, downloads — e virou o padrão de facto da faixa de badges que aparece no topo de quase todo README popular no GitHub. Como o badge é apenas a URL de uma imagem, funciona em Markdown, AsciiDoc, RST, HTML, wiki do JIRA e em qualquer lugar onde caiba um <img>.

O padrão mais simples de URL é https://img.shields.io/badge/Label-Message-color. Badges dinâmicos trocam esse caminho por uma rota que busca dados ao vivo — por exemplo /npm/v/express para a versão atual do express, ou /github/stars/torvalds/linux para o número de stars. O Shields faz cache de cada badge por cerca de cinco minutos, o que mantém o serviço rápido e poupa as APIs upstream.

Cores, estilos e logos

Cores nomeadas incluem brightgreen, green, yellow, orange, red, blue, lightgrey, mais os apelidos semânticos success, important, critical e informational; valores hex também funcionam (#ff69b4). Os parâmetros de estilo trocam a tipografia: ?style=flat (padrão), flat-square, plastic, for-the-badge (caixa alta e maior), social. Adicionar ?logo=github&logoColor=white embute o ícone da marca — o Shields puxa do SimpleIcons, que cobre mais de mil logos.

Endpoints dinâmicos úteis

• /npm/v/<pacote> — versão atual no npm
• /github/actions/workflow/status/<owner>/<repo>/<workflow>.yml — status do GitHub Actions
• /codecov/c/github/<owner>/<repo> — porcentagem de cobertura no Codecov
• /github/license/<owner>/<repo> — licença detectada automaticamente
• /github/last-commit/<owner>/<repo> — indicador de "está vivo"
• /endpoint?url=... — aponta para o seu próprio JSON, ideal para badges 100% personalizados

Anti-padrões comuns

Badges sinalizam maturidade e dão ao visitante um clique direto para o dashboard por trás de cada métrica — mas só funcionam quando curados. Alguns deslizes a evitar: inflação de badges — empilhar dez ou mais sufoca a descrição real, prefira quatro a seis essenciais; badges quebrados — manter um Travis CI depois de migrar para GitHub Actions, ou um Codecov após remover o upload de cobertura; badges sempre verdes — uma métrica que nunca falha não comunica nada, remova-a; tags decorativas — "Made with love" ou flair de stack agregam ruído visual sem informar o leitor.

Perguntas frequentes

Preciso hospedar alguma coisa? Não. O Shields.io hospeda todos os SVGs. Você só embute a URL.

O que acontece se o Shields bater no rate limit da API upstream? O badge cai em um estado genérico "invalid" e o Shields faz cache do erro por alguns minutos antes de tentar de novo. O README continua renderizando — só aquele badge fica esquisito até a API se recuperar.

Consigo personalizar o badge inteiramente? Sim. Hospede um JSON que exponha { "schemaVersion": 1, "label": "...", "message": "...", "color": "..." } e aponte um badge /endpoint?url=... para ele. Você controla label, valor, cor, logo e estilo.

Existem alternativas ao Shields? O Badgen.net espelha a maioria dos endpoints com customização extra, e o forthebadge.com traz um conjunto de estilo bem-humorado. O Shields segue como o mais abrangente e estável.