O que o GitHub README Stats mostra
GitHub README Stats é um projeto de código aberto que gera cartões SVG a partir do nome de usuário. O cartão principal pode mostrar estrelas, commits, pull requests, issues, contribuições e rank; outro cartão resume as linguagens dos repositórios.
Os números não medem toda a capacidade técnica. Visibilidade, atividade privada, forks, arquivos gerados, cache e limites de API alteram o resultado. Use o cartão como orientação rápida, não como nota profissional.
Coloque o cartão depois da apresentação ou dos projetos. Para objetivos específicos, consulte o guia de sequências, o guia de troféus, o modelo de README e o GitHub City.
O cartão inicia a conversa, mas os projetos fornecem a prova. Explique o problema, seu papel, as decisões técnicas e onde o código pode ser analisado.
Como adicionar e configurar um cartão
Teste primeiro a URL mínima e acrescente opções uma a uma para identificar erros com facilidade.
Abra o README do perfil
O repositório público deve ter exatamente o seu nome de usuário. Posicione o cartão após a bio ou os projetos.
Use o usuário correto
Troque o parâmetro username na URL oficial e abra a imagem diretamente para validar.
Escolha um tema legível
Garanta contraste no fundo real do README, tanto no modo claro quanto no escuro.
Mantenha opções úteis
Ícones e métricas ocultas devem melhorar a leitura, não apenas decorar.
Qual visual de perfil usar?
Cada widget responde a uma pergunta. Escolha um visual principal e, no máximo, um complemento.
| Visual | Melhor uso | Configuração | Limitação | Posição |
|---|---|---|---|---|
| Cartão de estatísticas | Visão geral | URL com usuário | Precisa de contexto | Após a bio |
| Linguagens principais | Mistura de linguagens | Cartão separado | Não mede habilidade | Perto das estatísticas |
| Streak Stats | Consistência recente | Serviço próprio | Exagera atividade diária | Só quando relevante |
| GitHub City | Calendário 3D interativo | Ferramenta no navegador | Não substitui projetos | Link aprofundado |
Problemas comuns
As causas mais comuns são usuário, URL, disponibilidade do serviço, visibilidade ou interpretação incorreta.
O cartão não carrega
Abra a imagem, confira usuário e parâmetros, remova opções e consulte o repositório oficial.
Os números parecem baixos
Confira repositórios, atividade privada, forks, cache e limites da API.
O tema está ilegível
Teste no fundo real e evite transparência com pouco contraste.
As linguagens confundem
Código gerado, notebooks ou um repositório grande podem dominar o gráfico.
Construa o perfil com evidências
Um bom perfil explica quem você é, o que constrói e qual código merece atenção. Projetos e resultados vêm antes dos widgets; um cartão apoia a história, muitos cartões competem com ela.
O guia de modelo README ajuda na estrutura. GitHub City oferece uma exploração memorável sem substituir a explicação do trabalho.
Revise o README em telas largas e móveis. Remova cartões repetidos e linhas largas demais para manter uma ordem de leitura clara.
Antes de publicar, consulte a documentação atual do projeto, pois parâmetros, temas e comportamento de cache podem mudar. Guarde uma URL mínima que funcione e adicione cada opção separadamente. Se uma combinação falhar, volte a essa base em vez de copiar configurações antigas de outros perfis.
Considere também acessibilidade e desempenho. Use texto alternativo descritivo, dimensões estáveis e um layout sem rolagem horizontal. O serviço externo pode ficar lento ou indisponível; por isso a bio e os links dos projetos precisam continuar compreensíveis mesmo quando a imagem não aparece.
Não esconda métricas apenas para deixar o rank mais atraente. Uma exclusão faz sentido quando código gerado, repositórios arquivados ou arquivos de terceiros distorcem a mensagem. A configuração deve ajudar a interpretar os dados, não criar uma afirmação mais forte do que as fontes permitem.
Por fim, confira todos os links depois de mudar a configuração. O repositório oficial deve continuar acessível para parâmetros atuais, e os guias de Streak, Trophy e README precisam apontar para a versão correta do idioma. Assim uma boa apresentação não esconde navegação quebrada nem recomendações antigas.
Também verifique a estabilidade das imagens externas. O perfil não deve depender de um único serviço. Se o cartão for importante para uma candidatura, mantenha links diretos para os repositórios e descreva resultados em texto normal e pesquisável.
Registre por que esse cartão foi escolhido para facilitar futuras revisões e evitar novos widgets sem utilidade clara.
Combinação recomendada
Bio curta, dois ou três projetos, um cartão de estatísticas e um visual opcional. Mantenha o restante em links descritivos.
Perguntas frequentes
É uma função oficial do GitHub?
Não. O README do perfil é do GitHub, mas o serviço de cartões é um projeto independente de código aberto.
Como adicionar estatísticas?
Insira no repositório de perfil o Markdown da imagem com seu usuário e confira a prévia.
Por que commits privados não aparecem?
Depende da visibilidade, dos dados disponíveis pela API e da configuração do serviço.
Stats, streaks ou troféus?
Stats resumem, streaks mostram consistência e troféus destacam marcos; escolha conforme a narrativa.
Posso combinar com GitHub City?
Sim. O cartão resume e o GitHub City aprofunda o calendário em 3D.