O que é um README de perfil do GitHub?
Um README de perfil do GitHub é um documento Markdown exibido no seu perfil público do GitHub quando você cria um repositório público com exatamente o mesmo nome do seu usuário e adiciona um arquivo README.md. No GitHub, esse repositório especial oferece um espaço estável para explicar seu foco, mostrar trabalhos selecionados e direcionar visitantes para links úteis.
A melhor primeira versão não é uma parede de badges. É uma página curta e fácil de ler sobre seu trabalho no GitHub: uma apresentação em uma frase, seu foco atual, dois ou três projetos com evidências e links que ajudam o visitante a dar o próximo passo. Você pode expandi-la depois de entender quais informações as pessoas realmente precisam.
Esta página se concentra em criar e publicar o README de perfil. Use o guia de modelos para definir a estrutura, o guia de ideias para buscar inspiração e o gerador para criar um primeiro rascunho copiável.
O que você precisa antes de começar
A configuração é simples, mas cada requisito importa. Um nome parecido, a visibilidade privada ou um arquivo fora do lugar podem deixar um README correto invisível. Confirme o básico antes de adicionar cores, badges ou widgets.
Trate o repositório do perfil como um pequeno projeto público do GitHub: use links reais, deixe o primeiro commit claro e nunca publique segredos ou afirmações sem comprovação. A documentação do GitHub é a referência final quando a interface muda.
| Requisito | Por que importa | Tenha em mente | Erro comum |
|---|---|---|---|
| Nome do repositório | O GitHub usa o repositório que corresponde ao usuário para identificar o README de perfil. | Copie seu nome de usuário exato, incluindo pontuação e maiúsculas quando o GitHub exigir. | Criar um repositório com nome de exibição, apelido ou sufixo extra. |
| Visibilidade pública | O README de perfil foi feito para ser visto pelos visitantes do perfil. | Verifique a visibilidade do repositório antes de investigar o Markdown. | Pressupor que um repositório privado será exibido como conteúdo público do perfil. |
| README.md | O arquivo Markdown é o documento que o GitHub renderiza no repositório e no perfil. | Coloque README.md na raiz do repositório e mantenha o nome do arquivo claro. | Salvar como README, colocá-lo em outra pasta ou deixar apenas um arquivo local que nunca foi commitado. |
| Primeiro rascunho útil | Os visitantes precisam de contexto e prova antes dos elementos decorativos. | Comece com uma bio curta, foco, projetos, links e uma próxima ação. | Abrir com uma longa fila de badges que esconda o que você realmente constrói. |
| Links seguros | Um README de perfil é público e costuma ser copiado ou compartilhado. | Revise URLs, e-mails, imagens, tokens e serviços incorporados antes de publicar. | Incluir segredos, painéis privados, links que expiram ou afirmações não verificadas. |
Como criar e adicionar um README de perfil do GitHub
Você pode criar o README de perfil pelo fluxo de novo repositório do GitHub ou fazer push de um repositório local. O importante é a relação entre o nome do repositório, a visibilidade pública e o arquivo README.md. Siga a sequência abaixo para isolar um problema de configuração em vez de adivinhar a sintaxe Markdown.
Depois que a primeira versão estiver no ar, trate as atualizações como trabalho normal de documentação. Visualize títulos e links, abra o perfil público sem sessão ou em uma janela privada quando possível e remova seções que já não descrevem seu trabalho atual.
Confirme seu nome de usuário exato
Abra seu perfil do GitHub e copie o usuário da URL do perfil. Não dependa apenas do nome mostrado no cabeçalho se ele for diferente do identificador da conta.
Crie o repositório público correspondente
Crie um novo repositório com exatamente o mesmo nome do seu usuário. Mantenha-o público se quiser que qualquer pessoa veja o README de perfil e inicialize-o com um README ou adicione o arquivo no passo seguinte.
Escreva o arquivo README.md
Comece com uma apresentação curta, foco atual, projetos selecionados e links úteis. Use títulos e parágrafos curtos para que o visitante possa examinar a página antes de decidir o que abrir.
Faça o commit e revise a página pública
Faça o commit do README na branch ativa do repositório, abra a página do repositório e verifique se o Markdown aparece sem imagens quebradas, links privados ou segredos acidentais.
Abra seu perfil e refine-o
Volte ao seu perfil público e confirme que o README de perfil aparece. Se não aparecer, use a lista de verificação abaixo antes de mudar o conteúdo ou adicionar mais widgets.
O que colocar no README
Um README de perfil do GitHub deve responder a quatro perguntas rápidas: quem é você, no que está trabalhando, o que o visitante pode conferir e para onde deve ir depois? Escolha seções que provem ou esclareçam algo; você não precisa de todos os widgets populares.
Use os exemplos abaixo como direção, não como texto para copiar. Uma frase sobre um projeto é mais forte quando leva a um repositório, demo, release, artigo ou captura que o leitor possa verificar.
Uma apresentação em uma linha
Diga seu papel ou direção com linguagem simples. Troque afirmações vagas por um foco concreto, como ferramentas de dados, acessibilidade no frontend ou documentação open source.
Foco atual
Mencione o que você está aprendendo, lançando ou mantendo agora. Isso dá um limite de tempo ao perfil e ajuda os visitantes a entender quais projetos estão ativos.
Projetos selecionados
Escolha dois ou três repositórios e explique o problema, sua contribuição e o resultado. Linke evidências em vez de listar todos os experimentos.
Links úteis
Adicione um portfólio, arquivo de textos, forma de contato ou perfil de comunidade quando for público, atual e realmente útil para o leitor.
Recursos visuais opcionais
Adicione badges, visuais de contribuições ou estatísticas somente depois de deixar a história principal clara, e remova tudo que estiver desatualizado ou for apenas decorativo.
Use modelos, geradores e recursos visuais na ordem certa
Um modelo é útil quando você precisa de uma estrutura inicial, não quando ele faz todos os perfis parecerem iguais. O guia de modelo de README de perfil ajuda você a decidir quais seções combinam e quais afirmações precisam de prova. O objetivo é um perfil que pareça seu e continue fácil de manter depois da primeira semana.
Um gerador pode acelerar o primeiro rascunho, mas não consegue verificar seus projetos nem escolher os limites da sua história pessoal. Use o gerador de README no navegador para criar um esqueleto copiável e depois edite o Markdown com base nos seus repositórios reais. Para ideias visuais, o guia de ideias para README de perfil é melhor para comparar opções do que uma coleção aleatória de badges.
Regra simples
Publique primeiro o perfil mais claro e útil. Adicione badges, estatísticas ou gráficos de contribuições somente quando cada elemento ajudar o visitante a entender seu trabalho ou escolher o próximo passo.
Por que seu README de perfil do GitHub não aparece
Quando o GitHub não exibe o README do perfil, confira as condições de publicação antes de reescrever o conteúdo. A maioria dos problemas é causada por diferenças no nome, visibilidade, caminho, branch ou conta, e não pela qualidade do Markdown.
| Problema | Causa provável | Solução |
|---|---|---|
| O nome do repositório é parecido, mas não é exato | O repositório foi criado com apelido, nome de exibição ou um caractere extra. | Compare o nome do repositório com o usuário na URL do seu perfil e corrija-o se necessário. |
| O repositório é privado | A visibilidade mudou durante a configuração ou o repositório foi criado em uma organização restrita. | Revise a visibilidade do repositório e a política da organização antes de esperar que visitantes públicos o vejam. |
| O arquivo não é README.md na raiz | O arquivo foi renomeado, colocado em uma pasta ou salvo apenas no seu computador. | Coloque README.md na raiz, faça commit na branch ativa e abra a página do repositório para confirmar a renderização. |
| O perfil mostra uma versão antiga | A edição mais recente não foi commitada, foi enviada para outra branch ou o navegador mostra conteúdo em cache. | Confira o histórico de commits e a branch ativa; depois atualize o perfil ou abra-o em uma janela privada. |
| Imagens ou badges estão quebrados | Foi usada uma rota relativa, um asset privado, uma branch renomeada ou uma URL externa expirada. | Abra cada URL de asset na página renderizada do repositório e substitua fontes instáveis ou privadas. |
| A página é difícil de ler | Há widgets demais, parágrafos longos ou títulos que não correspondem ao conteúdo. | Suba a apresentação e as provas dos projetos, encurte as seções e remova blocos decorativos que não ajudam o visitante. |
Perguntas frequentes sobre READMEs de perfil do GitHub
Um README de perfil do GitHub é gratuito?
Sim. O README de perfil usa recursos de repositórios e Markdown do GitHub, então você pode criá-lo sem comprar um site ou plano de hospedagem separado. Ainda é necessário respeitar as configurações da conta, da organização e da visibilidade do repositório.
Qual deve ser o nome do repositório do README de perfil?
Use um nome de repositório que corresponda exatamente ao seu nome de usuário do GitHub. Compare a URL do repositório com a URL do perfil em vez de confiar apenas no nome exibido na interface.
Um repositório privado pode alimentar um README de perfil?
Um repositório privado não é uma forma confiável de publicar um README de perfil para visitantes públicos. Confira a documentação atual do GitHub e a visibilidade do repositório antes de investigar o Markdown.
Posso usar um gerador de README de perfil do GitHub?
Sim. Um gerador pode ajudar com um primeiro esboço ou com a sintaxe Markdown, mas revise cada frase, link de projeto, imagem, badge e afirmação comparando-os com seu perfil real antes de publicar.
O que devo evitar em um README de perfil?
Evite segredos, URLs privadas, badges antigos, animações excessivas, afirmações não verificadas e blocos longos que escondam seu trabalho atual. Uma documentação pública deve ser fácil de ler e segura para compartilhar.