Como escrever um README no Github: exemplos, dicas e guia passo a passo
14 minutos de leitura
Ao criar ou subir um projeto no GitHub, um dos primeiros pontos de atenção deve ser o arquivo README.md.
Mas qual a diferença entre ter ou não ter um README bem feito em seu repositório? Confira este exemplo:
Repositório: GlicoCare2
Repositório: GlicoCare
Com certeza a segunda opção, não é mesmo?
Na primeira opção, não sabemos claramente do que se trata o projeto. Já o diferencial do segundo repositório é ter um arquivo README, que torna o projeto mais atrativo e explicativo.
Ter um README.md completo é fundamental para explicar do que se trata o seu projeto, facilitar o entendimento por outros usuários do GitHub e valorizar seu portfólio.
Neste artigo, entenda como fazer um README, veja exemplos reais de README no GitHub e aprenda passo a passo como criar um arquivo README.md de sucesso.
README no GitHub: o que é, para que serve e como criar seu arquivo README.md
O README é um arquivo com extensão .md, escrito em Markdown, uma linguagem de marcação que converte texto em HTML válido. Caso queira saber mais, consulte este artigo sobre como funciona o Markdown e como escrever anotações com essa linguagem.
O arquivo README.md é o cartão de visitas do seu repositório no GitHub. Ele serve para apresentar as informações essenciais do projeto, facilitar a colaboração e informar rapidamente visitantes e recrutadores sobre as funcionalidades, instalação e uso.
Nas plataformas de repositórios remotos, como o GitHub, a função desse arquivo é apresentar informações do projeto, como:
- Descrição do seu projeto;
- Funcionalidades;
- Como os usuários podem utilizá-lo;
- Onde os usuários podem encontrar ajuda sobre seu projeto;
- Autores do projeto.
Por que criar um README.md para seu projeto no GitHub?
Depois de desenvolver seu projeto, é essencial criar um README.md claro e bem estruturado antes de subir para o GitHub. O arquivo README do seu repositório explica rapidamente do que se trata o projeto e como outros podem utilizá-lo.
Para isso, é legal documentar o projeto para quem for visitar seu repositório saiba do que se trata, assim como foi visto no primeiro exemplo.
O README.md geralmente é o primeiro arquivo que aparece ao acessar um repositório do GitHub. Ele é a porta de entrada do seu projeto e, muitas vezes, determina se alguém vai seguir em frente para ver o restante do código ou não.
O próprio GitHub recomenda fortemente adicionar um arquivo readme.md logo na criação do repositório.
Tradução: Ajude as pessoas interessadas neste repositório a entender seu projeto adicionando um README.
Além disso, algumas pessoas utilizam o perfil GitHub como portfólio, se esse for o seu caso, é interessante apostar em arquivos README para deixar seus projetos mais atrativos até mesmo para recrutadores, como explicado nesse artigo da Jornada de um estagiário.
Se esse não for seu objetivo, é válido destacar que nem sempre será necessário adicionar um README, especialmente quando o repositório não visa colaboração ou interesse de terceiros.
O que não pode faltar em um arquivo README.md: elementos essenciais
Repositórios de destaque frequentemente apresentam arquivos README bem elaborados.
Por exemplo, o repositório Docusaurus do Facebook auxilia na construção, implantação e manutenção de sites para projetos de código aberto
Já o projeto Open MCT, da NASA, é voltado para análise de dados de missões espaciais, além do planejamento e operação de sistemas experimentais.
Confira abaixo os principais itens que você deve considerar para fazer um README.md completo e atrativo no GitHub, incluindo exemplos reais encontrados em repositórios de referência. Estas dicas são válidas se você busca saber como fazer um readme de um projeto ou como criar um readme bonito no GitHub.
- Título e Imagem de capa;
- Badges;
- Índice;
- Descrição do Projeto;
- Status do Projeto;
- Funcionalidades e Demonstração da Aplicação;
- Acesso ao Projeto;
- Tecnologias utilizadas;
- Pessoas Contribuidoras;
- Pessoas Desenvolvedoras do Projeto;
- Licença.
Como adicionar título e imagem de capa no README.md do GitHub
Ao adicionar um README, o título padrão será o nome do seu repositório, mas é possível personalizá-lo e incluir um nome mais descritivo e criativo.
Ao escolher o título, você pode colocá-lo dessa maneira:
# Seu título aqui Ou, caso queira colocar ele centralizado, você pode utilizar tags do HTML que funcionam normalmente, dessa forma:
<h1 align="center"> Seu título aqui </h1> Feito isso, caso queira, você pode fazer uma capa ou logo do projeto para colocar após o título. Particularmente, gosto bastante do Canva para fazer artes.
O plano gratuito oferece 2+ milhões de templates, 4.7+ milhões de fotos e gráficos gratuitos, e 5GB de armazenamento em nuvem, sendo uma opção funcional para criar capas de projetos. Caso queira aprender mais, confira nosso Curso de Introdução ao Canva.
Se a logo for uma arte que represente o título (como no exemplo do GlicoCare), ela pode substituir o título textual:
Porém, pode ser utilizados os dois também, como utilizado no Docusaurus:
Ou CacheLib do Facebook também:
Mas como colocar a imagem no arquivo? Assim que você fizer ou encontrar sua arte, você pode abrir ela no explorador de arquivos e arrastá-la para o arquivo do README em edição, segue um exemplo feito no Windows:
Dentro dos colchetes [], irá aparecer o nome do arquivo da imagem como descrição, mas é interessante que você descreva detalhadamente do que se trata para ajudar na acessibilidade. E dentro dos parênteses aparece um link da sua imagem que o GitHub gera ao converter e hospedar ela.
Uma alternativa mais segura é subir a imagem para seu próprio repositório ou usar serviços de hospedagem, como Imgur ou Pasteboard, e então utilizar o link gerado para inserir em Markdown:
 Você também pode utilizar imagens disponibilizadas na internet pegando o link e colocando da mesma forma citada anteriormente, porém não é recomendado, pois há risco do link expirar e a imagem deixar de ser exibida.
Como adicionar badges no README do GitHub
Alguns repositórios utilizam badges, que são distintivos visuais para indicar informações como o estado atual do projeto, licença, versões, dependências, testes, entre outros.
Um exemplo do uso de badges em um repositório do Dropbox, o Dropbox Core SDK for Java 8+:
Nele foi utilizado badges para:
- Licença: Instituto de Tecnologia de Massachusetts (MIT);
- Versão da ferramenta de gerenciamento de dependências, Maven: versão 4.0.1;
- Data da última versão do projeto: agosto.
Para criar suas próprias badges, use o site Shields.io. Lá você encontra exemplos prontos e pode inserir o link do seu repositório do GitHub para receber sugestões de badges de acordo com seu projeto. O site fornece o código Markdown pronto para ser copiado no README.
Exemplos:
1. Status do projeto:
Código gerado:
 Resultado:
Caso queira deixar centralizado, pode utilizar a tag align do HTML também, dessa forma:
<p align="center">
<img loading="lazy" src="http://img.shields.io/static/v1?label=STATUS&message=EM%20DESENVOLVIMENTO&color=GREEN&style=for-the-badge"/>
</p>2. Stars do projeto:
Código gerado:
 Resultado:
Como criar um índice no README.md para facilitar navegação no GitHub
O GitHub pode gerar automaticamente um índice para arquivos README, com base nos títulos das seções. Para acessá-lo, clique no ícone de menu no canto superior esquerdo do arquivo.
Principalmente em READMEs extensos, essa é uma ferramenta excelente para navegar pelo documento, pois redireciona o usuário para o tópico selecionado.
Entretanto, se desejar, também é possível criar manualmente um índice em Markdown, facilitando ainda mais a navegação dentro do arquivo.
Exemplo:
# Índice
* [Título e Imagem de capa](#Título-e-Imagem-de-capa)
* [Badges](#badges)
* [Índice](#índice)
* [Descrição do Projeto](#descrição-do-projeto)
* [Status do Projeto](#status-do-Projeto)
* [Funcionalidades e Demonstração da Aplicação](#funcionalidades-e-demonstração-da-aplicação)
* [Acesso ao Projeto](#acesso-ao-projeto)
* [Tecnologias utilizadas](#tecnologias-utilizadas)
* [Pessoas Contribuidoras](#pessoas-contribuidoras)
* [Pessoas Desenvolvedoras do Projeto](#pessoas-desenvolvedoras)
* [Licença](#licença)
* [Conclusão](#conclusão)Resultado:
• Título e Imagem de capa
• Badges
• Índice
• Descrição do Projeto
• Status do Projeto
• Funcionalidades e Demonstração da Aplicação
• Acesso ao Projeto
• Tecnologias utilizadas
• Pessoas Contribuidoras
• Pessoas Desenvolvedoras do Projeto
• Licença
• Conclusão
Como escrever uma boa descrição no arquivo README.md do seu projeto
Como o principal objetivo do README é descrever o projeto, apresente uma breve explicação logo após o título, imagem de capa ou badges, destacando o objetivo do projeto.
Você pode adotar uma descrição mais objetiva, como a do Dropbox Core SDK for Java 8+:
Tradução: Uma biblioteca Java para acessar a API Core v2 baseada em HTTP do Dropbox. Este SDK também oferece suporte ao Core API v1 mais antigo, mas esse suporte será removido em algum momento.
Ou pode detalhar mais, como feito no projeto GlicoCare e apresentar figuras que exemplificam o projeto, caso tenha:
Como exibir o status do projeto no README.md
Se não utilizar badges para indicar o status do projeto, inclua essa informação em texto diretamente no arquivo. Exemplo:
> :construction: Projeto em construção :construction: Resultado:
🚧 Projeto em construção 🚧
Ou caso queira centralizar:
<h4 align="center">
:construction: Projeto em construção :construction:
</h4>No exemplo, foi utilizado o emoji :construction:, mas outros emojis podem ser incorporados em diferentes partes do arquivo, inclusive em subtítulos. No Gist do Rafael Xavier de Souza, há uma variedade de emojis para personalizar seu README.
Como listar funcionalidades e adicionar demonstração no README.md do GitHub
Você pode listar as funcionalidades do seu projeto para facilitar o entendimento do usuário. Para isso, você pode fazer dessa maneira:
# :hammer: Funcionalidades do projeto
- `Funcionalidade 1`: descrição da funcionalidade 1
- `Funcionalidade 2`: descrição da funcionalidade 2
- `Funcionalidade 2a`: descrição da funcionalidade 2a relacionada à funcionalidade 2
- `Funcionalidade 3`: descrição da funcionalidade 3Resultado:
🔨 Funcionalidades do projeto
• Funcionalidade 1: descrição da funcionalidade 1
• Funcionalidade 2: descrição da funcionalidade 2
• Funcionalidade 2a: descrição da funcionalidade 2a relacionada à funcionalidade 2
• Funcionalidade 3: descrição da funcionalidade 3
Além disso, se for possível, é interessante apresentar as funcionalidades com um exemplo visual do projeto, como gif, imagens ou vídeo. Segue como exemplo o gif que foi utilizado no repositório Android com Kotlin - Personalizando UI:
Lembrando que o procedimento para colocar gif é o mesmo adotado para imagens e você pode gravar gifs com gravadores de tela, como o Acethinker, o OBS Studio ou o Kap (macOS).
Como colocar link no README do GitHub e orientar acesso ao projeto
Caso o seu projeto esteja no ar com algum serviço de hospedagem, você pode disponibilizar o link para o mesmo. Caso contrário, você pode apostar em gifs e imagens, como citado anteriormente, bem como indicar como o usuário pode baixar o projeto, abrir e executar.
Novamente, tendo como exemplo o repositório Android com Kotlin - Personalizando UI que citou como o usuário pode ter acesso ao projeto, bem como abrir e rodar o mesmo:
Como pode ser feito em Markdown:
# 📁 Acesso ao projeto
**Indique como é possível baixar ou acessar o código fonte do projeto, seja projeto inicial ou final**
# 🛠️ Abrir e rodar o projeto
**Apresente as instruções necessárias para abrir e executar o projeto**Como listar tecnologias utilizadas no seu arquivo README.md
Você também pode citar as tecnologias utilizadas no projeto, é uma ótima forma de demonstrar o que você anda estudando nesse mar que é a tecnologia.
Você pode citar com textos, como o que foi feito no repositório Edige - POO:
Como listar contribuidores no README.md do GitHub
Se houver pessoas contribuidoras no projeto, adicione-as ao README, incluindo, se possível, fotos e links de perfil. No projeto Docusaurus, há inclusive uma seção dedicada com fotos e um link adicional para informações a quem deseja contribuir.
Como apresentar autores do projeto no arquivo README.md
E agora entra você! É importante que você coloque sua foto também, caso não goste de fotos, vale o user padrão do GitHub ou fazer seu próprio Octocat. Além disso, você pode linkar seu usuário, para caso algum usuário queira entrar em contato ou reportar algo.
# Autores
| [<img loading="lazy" src="https://avatars.githubusercontent.com/u/37356058?v=4" width=115><br><sub>Camila Fernanda Alves</sub>](https://github.com/camilafernanda) | [<img loading="lazy" src="https://avatars.githubusercontent.com/u/30351153?v=4" width=115><br><sub>Guilherme Lima</sub>](https://github.com/guilhermeonrails) | [<img loading="lazy" src="https://avatars.githubusercontent.com/u/8989346?v=4" width=115><br><sub>Alex Felipe</sub>](https://github.com/alexfelipe) |Resultado:
Como adicionar licença no README.md do seu projeto GitHub
Repositórios públicos no GitHub costumam ser utilizados para compartilhar softwares de código aberto. No entanto, é fundamental incluir uma licença, pois só assim terceiros terão permissão para usar, modificar e distribuir seu software
Portanto, caso seu repositório tenha uma licença, é essencial que você coloque ela no seu README. Como feito no Docusaurus:
Tradução: Docusaurus é licenciado pelo MIT. A documentação do Docusaurus (por exemplo, arquivos .md na pasta ./docs) é licenciada pelo Creative Commons.
Exemplos de README no GitHub para se inspirar
Segue todos os READMEs citados aqui, bem como alguns para se inspirar:
- Docusaurus;
- Open MCT;
- GlicoCare;
- CacheLib;
- Dropbox Core SDK for Java 8+;
- Edige - POO;
- Android com Kotlin - Personalizando UI.
E para se inspirar, segue alguns templates legais:
- Template de README em Português feito pela Diana Regina, que é um presente do artigo da autora, o qual foi referência para escrita desse;
- Template de README em Inglês do Othneil Drew.
Lembrando que para olhar o código fonte, em Markdown, clique na opção Raw no canto superior direito do README:
Como criar um README.md para o GitHub do jeito certo: passo a passo final
Se você quer aprofundar e aprender de forma prática, confira nossos cursos de Git e GitHub com projetos reais, onde ensinamos passo a passo como criar um arquivo README.md para o GitHub do jeito certo, além de diversos templates para começar seu novo projeto.
E para aprender mais sobre Git e GitHub, confira:
- Websérie: Git e Github para sobrevivência | com DevSoutinho
- Curso de Git e Github: Controle e compartilhe seu código
- Curso de Git e Github: Estratégias de ramificação, Conflitos e Pull Requests
E tem um video incrível do DevSoutinho, um Alura Star, que também aborda o Readme:
