O que torna um badge de README do GitHub útil?
Um badge no README do GitHub é uma imagem pequena, geralmente próxima ao título do projeto, que comunica um fato verificável. Status do build, versão do pacote, licença, documentação e cobertura são exemplos comuns. A imagem não é a prova completa: o link deve levar à fonte.
Bons badges reduzem a dúvida de quem decide instalar, usar, contribuir ou confiar em um repositório. Um badge de workflow pode mostrar se as verificações principais passaram; um badge de release indica se o projeto é mantido; um badge de licença ajuda a encontrar as condições de reutilização.
Não confunda badges de README com GitHub Achievements, Profile Trophy ou imagens de contribuições. O guia de GitHub Achievements cobre os badges oficiais do perfil, enquanto o guia de ideias para Profile README mostra como usar visuais sem esconder a prova do projeto.
A primeira linha deve ser fácil de ler no celular. Se o visitante precisar atravessar dez badges antes de chegar à explicação do projeto, a decoração está atrapalhando. Mantenha primeiro os fatos que mudam a próxima decisão e mova o restante para baixo.
Sintaxe Markdown para badges do GitHub
A maioria dos badges de README usa a sintaxe comum de imagem Markdown. A URL da imagem vem primeiro; o link ao redor dela permite abrir a prova. Use um texto alternativo curto e claro para o caso de a imagem não carregar.
O Shields.io gera badges a partir de serviços compatíveis ou de rótulos e valores definidos. Use o formato documentado pelo provedor, sem adivinhar parâmetros. Quando uma API muda, uma URL inventada pode virar uma imagem quebrada ou um dado antigo.
O exemplo liga um badge de build à página do workflow. Troque o repositório e o endpoint pelos do seu projeto e abra o README sem login para confirmar que imagem e destino são públicos.
[](https://github.com/your-name/your-repo/actions)| Tipo | Fonte Markdown comum | O que deve provar |
|---|---|---|
| Build | endpoint de workflow ou CI | Se os checks analisados passaram para a branch ou contexto indicado. |
| Release | última release ou versão do pacote | Qual versão o leitor deve conferir ou instalar. |
| Licença | badge de licença do repositório | Onde consultar as permissões antes de reutilizar o código. |
| Documentação | link para docs ou referência de API | Um caminho direto para configuração e uso. |
| Cobertura | endpoint de serviço de cobertura | Um sinal de testes somente quando a métrica é mantida e explicada. |
Um fluxo de manutenção para badges do README
Adicionar badges é simples; mantê-los corretos é o trabalho real. Revise a linha quando mudar o provedor, a branch, o nome do pacote, o processo de release, a documentação ou a licença. Um badge correto há seis meses pode enganar depois de uma migração.
Antes de adicionar uma imagem, escreva a frase que ela deve apoiar. “Parece profissional” não é uma boa função. “O leitor pode confirmar a versão atual sem procurar no repositório” é uma função clara.
O guia de modelo de Profile README ajuda a ordenar provas do projeto e visuais. Se houver cards de atividade próximos, veja o guia do GitHub README Stats para não repetir a mesma informação.
Escolha a pergunta do leitor
Decida se o badge fala de build, release, licença, documentação, compatibilidade ou qualidade. Não comece por uma coleção de cores.
Encontre a fonte de verdade
Use workflow oficial, registro de pacotes, arquivo de licença, documentação ou provedor de métrica mantido.
Adicione imagem e link
Use Markdown, alt útil e link para a evidência. Deixe o código compreensível para a próxima manutenção.
Confira o README renderizado
Abra a página do repositório no computador e no celular. Verifique imagens, destinos, contraste e quebra de linha.
Revise depois das mudanças
Confira os badges após mudar branch, CI, pacote, release, documentação ou licença e remova dados antigos.
Quais badges do README do GitHub escolher?
Não existe um conjunto universal. A escolha depende da decisão do leitor. Uma biblioteca pode usar release, pacote, licença, documentação e CI. Um projeto de portfólio pode precisar apenas de demo, status de deploy e uma explicação técnica curta.
Mantenha o tema nos badges de README. Badges de repositório, Achievements do perfil, Profile Trophy, gráficos de contribuições e README Stats têm intenções diferentes e devem ficar em guias separados ou links de apoio.
Status do build
Use quando testes ou deploy forem importantes. Ligue para checks ou workflow, não apenas para a página inicial do repositório.
Release ou pacote
Mostre uma fonte atual quando o leitor precisar saber o que instalar ou conferir. Evite manter a versão manualmente em dois locais.
Licença
Mantenha quando os direitos de reutilização forem importantes e ligue para o arquivo de licença real.
Documentação
É útil para bibliotecas, APIs e ferramentas quando leva a um guia de início ou referência mantida.
Cobertura ou qualidade
Mostre apenas quando o significado for claro e o provedor estável. Número sem contexto pode reduzir a confiança.
Como corrigir badges quebrados no README
Quando um badge não aparece ou deixou de ser verdadeiro, investigue a fonte antes de trocar de provedor. Estes testes cobrem falhas comuns de Markdown e manutenção.
| Problema | Causa provável | Correção |
|---|---|---|
| A imagem está quebrada | Endpoint, caminho, consulta ou provedor mudou. | Abra a URL diretamente, consulte a documentação e atualize ou remova o badge. |
| A imagem está antiga | Um valor manual ou URL de release antiga ficou no README. | Aponte para uma fonte viva e compare com release, workflow ou pacote. |
| O link abre a página errada | O link Markdown foi copiado de outro repositório. | Abra o destino sem login e ligue para a evidência exata. |
| A linha fica larga no celular | Muitos badges, rótulos longos ou tabela larga. | Mantenha os badges decisivos, mova detalhes para baixo e teste uma largura pequena. |
| A métrica privada não aparece | O provedor não consegue ler o repositório privado. | Use fonte pública, explique a limitação ou remova o badge. |
| O README parece uma parede de widgets | Badges, stats, streaks e achievements repetem o mesmo sinal. | Coloque a prova do projeto primeiro e mantenha apenas sinais diferentes. |
Perguntas frequentes sobre badges do GitHub
Como adicionar badges a um README do GitHub?
Adicione uma imagem Markdown e, se necessário, um link para workflow, release, licença ou documentação. Depois confira a página pública do repositório.
Quais badges são úteis em um projeto?
Escolha os que respondem a uma dúvida real sobre build, release, pacote, licença, documentação ou métrica mantida. Uma linha curta costuma ser suficiente.
Posso usar badges em um Profile README?
Sim, mas a identidade e a prova dos projetos vêm primeiro. O guia de ideias para Profile README mostra como evitar excesso de widgets.
Badges do README são GitHub Achievements?
Não. Os primeiros são imagens Markdown escolhidas pelo autor; Achievements são badges oficiais de perfil administrados pelo GitHub.
Devo usar Shields.io em todos os badges?
Não. Use endpoints documentados e estáveis, mas prefira o provedor oficial quando a origem do status ficar mais clara e evite duplicações.
Quantos badges um README deve ter?
Não há número fixo. Comece com o mínimo que ajude a instalar, confiar ou contribuir e remova o que for decorativo, repetido ou antigo.