Como edito os readme.md dos meus repositórios no Github ?

O readme de um repositório no github tem o objetivo de esclarecer as principais curiosidades sobre aquele projeto. Por isso, saber quais informações inserir e como demonstrar algo que tem por vir já na apresentação é interessante.

Quando comecei meus projetos no github, formatava os readme.md dos meus projetos conforme o meu primeiro treinamento sobre git e github que fiz na Udemy.

Era simples e continha as principais informações. Eu tomei cuidado de colocar algumas informações que julgava importantes.

Encontrei um artigo muito interessante com orientações de como formatar o readme.md de um repositório no github,

Vou reformatar o readme de um dos meus repositórios no github. A seguir está como foi formatado inicialmente.

Essa edição do readme tem como resultado o seguinte layout

Vou formatar um e demonstrar aqui como ficou e depois fazer nos demais projetos. Segundo o artigo que citei, trata-se de um Guia Rocketseat para um README de qualidade.

Vamos aprender como estruturar um bom README. No final vou deixar um template baseado no que vamos aprender e indicar referências interessantes que encontrei sobre o assunto.

Apresentado as duas categorias, opcional e obrigatório.

Estrutura do README

Essa é uma sugestão de estrutura, cada um pode fazer conforme a necessidade do projeto. Vamos agora cobrir cada um dos tópicos da estrutura e outros pontos adicionais.

Logo ou Banner

Status: Opcional

Se seu projeto já tem uma logo adicione no README. Pode ser um banner também. Você pode criar uma logo ou banner usando o Canva.

A logo ou banner podem substituir o título, mas não a descrição do projeto, veja um exemplo. O bom de manter o título e descrição em texto é que ajuda no SEO do Github, o Google vai ajudar indexar melhor seu projeto nas primeiras páginas de pesquisas, além de dar um resumo sobre o seu projeto.

Título e Descrição

Status: Obrigatório

Título: Nome curto do projeto

Descrição: Uma breve descrição do objetivo do projeto.

# Nome do Projeto 
ou
<h1 align="center">Nome do Projeto</h1>

Nome do Projeto

Com a descrição:

## Descrição do Projeto
<p align="center">Escrever uma breve descrição</p>

Escrever uma breve descrição

<h1 align="center">
<a href="https://pt-br.reactjs.org/">🔗 React</a>
</h1>
<p align="center">🚀 lib para construir interfaces do usuário com componentes reutilizáveis</p>

🔗 React

🚀 lib para construir interfaces do usuário com componentes reutilizáveis

Badges

Status: Opcional

É uma questão de gosto pessoal e comunicação. As badges são úteis para indicar o status do projeto: você pode colocar a versão dele, link para licença, quantidade de issues, status da build, status dos testes. Vale muito a pena colocar.

As badges podem ficar no topo antes do título ou abaixo da descrição. Use o site shields.io para gerar suas badges.

Você pode criar a sua própria badge:

Os ícones de várias logos de produtos e tecnologias você encontra aqui: simpleicons.org.

Podemos customizar partir da URL a abaixo:

https://img.shields.io/static/v1?label=<LABEL>&message=<MESSAGE>&color=<COLOR>&style=<STYLE>&logo=<LOGO>

Os parâmetros significam:

  • LABEL: texto do campo esquerdo
  • MESSAGE: texto do campo direto
  • COLOR: cor do campo direito, pode usar RGB.
  • STYLE: estilo do badge inteiro. Podemos ter: plastic, flat, for-the-badge, social ou flat-square. Teste cada uma delas.
  • LOGO: logo do campo esquerdo

Como exemplo, vou escolher os seguintes parâmetros:

  • LABEL: como Blog
  • MESSAGE: como Rocketseat
  • COLOR: 7159c1
  • STYLE: como for-the-badge
  • LOGO: como GHOST

Podemos colocar ele no README assim em HTML:

<img src="https://img.shields.io/static/v1?label=Blog&message=Rocketseat&color=7159c1&style=for-the-badge&logo=ghost"/>

ou ainda em Markdown:

![Badge](https://img.shields.io/badge/Blog-Rocketseat-%237159c1?style=for-the-badge&logo=ghost)

Pronto. Veja como ficou o badge personalizado:

Legal que no site shields.io tem o input search / project URL que você cola o link do projeto do seu Github e ele sugere alguns badges.

Tem esse repositório com algumas badges prontas: Naereen/badges

Tabela de Conteúdos

Status: Obrigatório

É ótimo colocar os índices de conteúdos, que é tabela onde a pessoa clica e vai para o tópico específico.

Exemplo com markdown:

Tabela de conteúdos ================= <!--ts--> * [Sobre](#Sobre) * [Tabela de Conteudo](#tabela-de-conteudo) * [Instalação](#instalacao) * [Como usar](#como-usar) * [Pre Requisitos](#pre-requisitos) * [Local files](#local-files) * [Remote files](#remote-files) * [Multiple files](#multiple-files) * [Combo](#combo) * [Tests](#testes) * [Tecnologias](#tecnologias) <!--te-->

Resultado:

Tabela de conteúdos

Se o README tiver poucos tópicos pode fazer inline, com HTML:

<p align="center"> <a href="#objetivo">Objetivo</a> • <a href="#roadmap">Roadmap</a> • <a href="#tecnologias">Tecnologias</a> • <a href="#contribuicao">Contribuição</a> • <a href="#licenc-a">Licença</a> • <a href="#autor">Autor</a> </p>

Resultado:

ObjetivoRoadmapTecnologiasContribuiçãoLicençaAutor

No README.md do Github você pode usar HTML o que ajuda muito. 👌

Status do Projeto

Status: Obrigatório

Indica se o projeto está em desenvolvimento ou já foi concluído.

<h4 align="center"> 
🚧 React Select 🚀 Em construção... 🚧
</h4>

Resultado:

🚧 React Select 🚀 Em construção… 🚧

Features

Status: Opcional

Você pode listar as funcionalidades da aplicação.

É opcional, porém é muito importante colocar. Isso ajuda demais as pessoas entenderem o que já tem feito, se estiver em construção você vai checkando o que está pronto.

Exemplo:

### Features- [x] Cadastro de usuário
- [x] Cadastro de cliente
- [ ] Cadastro de produtos

No Github ou gist fica com essa aparência abaixo. Resultado:

Demonstração da aplicação

Status: Opcional

Se for um projeto web e estiver hospedado em algum lugar, forneça o link. Se o deploy foi feito no Netlify tem um badge para isso.

Se for uma API backend pode customizar um badge com um ícone do heroku. Pode também colocar o arquivo do Insomnia para ficar mais rápido para o usuário testar a API — Fica muito bom.

Se a aplicação estiver em desenvolvimento, se for um app mobile ou website coloque os prints da tela ou um gif ilustrando a utilização.

Exemplos de como usar imagens e gifs no README:

animavita/animavita

Trigger life-saving alerts, register animals for adoption and find the closest pet friend to adopt :dog: — animavita/animavita

animavitaGitHub

tgmarinho/meetapp

Final Challenge of Rocketseat Bootcamp | Meetapp Backend, Frontend and Mobile — tgmarinho/meetapp

tgmarinhoGitHub

lukemorales/rocketshoes-react-native

NetShoes Clone with React Native and Redux. Contribute to lukemorales/rocketshoes-react-native development by creating an account on GitHub.

lukemoralesGitHub

A maneira mais segura de manter os arquivos é criar uma pasta screenshots, github, assets, resources ou nome que você quiser e deixar os arquivos nela. Se você usar um CDN de imagens ou gif pode funcionar mas corre o risco do quebrar o link algum dia.

Supondo que você tenha criado uma pasta assets no seu projeto e tem o arquivo banner.png, é assim que você pode adicionar a imagem:

<h1 align="center">
<img alt="NextLevelWeek" title="#NextLevelWeek" src="./assets/banner.png" />
</h1>

Resultado:

Exemplo de como adicionar um banner com markdown:

![Thiago Marinho](https://pbs.twimg.com/profile_banners/41742474/1490016588/1500x500)

Nesse caso estou usando algo genérico, usando uma imagem minha do banner do meu perfil no Twitter.

Outra maneira:

* SignUp Mobile![SignUp Mobile](screenshots/signup-mobile.png)

Eu prefiro usar as tags HTML porque permitem customizar melhor, centralizar e diminuir a imagem.

Se quiser arriscar com algum serviço de hospedagem tem essa opção: imgur.com, se for um gif pode usar esse aqui giphy.com.

Pré-requisitos e como rodar a aplicação/testes

Status: Obrigatório

Se o projeto for uma lib, você tem que mostrar os passos de como instalar e usar a lib, se for um projeto backend | web | mobile | desktop descreva os passos de como fazer para rodar na máquina.

Se tiver testes é bom descrever como rodar os testes.

Exemplo:

### Pré-requisitosAntes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas:
[Git](https://git-scm.com), [Node.js](https://nodejs.org/en/).
Além disto é bom ter um editor para trabalhar com o código como [VSCode](https://code.visualstudio.com/)
### 🎲 Rodando o Back End (servidor)```bash
# Clone este repositório
$ git clone <https://github.com/tgmarinho/nlw1>
# Acesse a pasta do projeto no terminal/cmd
$ cd nlw1
# Vá para a pasta server
$ cd server
# Instale as dependências
$ npm install
# Execute a aplicação em modo de desenvolvimento
$ npm run dev:server
# O servidor inciará na porta:3333 - acesse <http://localhost:3333>
```

✨ Resultado:

Pré-requisitos

Antes de começar, você vai precisar ter instalado em sua máquina as seguintes ferramentas:
Git, Node.js.
Além disto é bom ter um editor para trabalhar com o código como VSCode

🎲 Rodando o Back End (servidor)

# Clone este repositório
$ git clone <https://github.com/tgmarinho/nlw1>
# Acesse a pasta do projeto no terminal/cmd
$ cd nlw1
# Vá para a pasta server
$ cd server
# Instale as dependências
$ npm install
# Execute a aplicação em modo de desenvolvimento
$ npm run dev:server
# O servidor inciará na porta:3333 - acesse <http://localhost:3333>

✅ Tecnologias utilizadas

Status: Obrigatório para projetos de portfólio/estudos.

Listar as tecnologias e colocar os links para o seus respectivos sites é um plus no README.

### 🛠 TecnologiasAs seguintes ferramentas foram usadas na construção do projeto:- [Expo](https://expo.io/)
- [Node.js](https://nodejs.org/en/)
- [React](https://pt-br.reactjs.org/)
- [React Native](https://reactnative.dev/)
- [TypeScript](https://www.typescriptlang.org/)

Resultado:

🛠 Tecnologias

As seguintes ferramentas foram usadas na construção do projeto:

✅ Contribuição

Status: Opcional

Se seu projeto começar a receber contribuições, uma maneira legal de reconhecer o trabalho dessas pessoas é adicionando na lista de contribuidores.

Com certeza eles contribuíram porque gostam do projeto, e vão amar ♥️ receber esse esse reconhecimento.

Segue um modelo bem legal:

Eles utilizaram um bot pra criar essa lista: https://allcontributors.org/docs/en/bot/overview

Mas se não usar algo complexo, pode fazer simples: Link para exemplo.

Resultado:

É bom colocar o arquivo CONTRIBUTING.md na raiz do projeto para os devs saberem os passos de como contribuir no projeto.

✅ Autor

Status: Obrigatório

Aqui entra seu jabá, interessante colocar seus contatos, redes sociais para as pessoas te encontrarem e começar um networking:

Link com o template de exemplo.

Resultado:

✅ Licença

Status: Obrigatório

Precisa definir a licença do seu projeto. Se você não souber definir, leia isso e isto.

A maioria dos devs utilizam a licença MIT que permite as pessoas baixarem o projeto e modificar e você não será responsabilizado por nada.

Muito simples escolher uma licença, o github te ajuda com isso te dando um template.

Geralmente você cria um arquivo LICENSE.

Exemplo:

MIT LicenseCopyright (c) <2020> <Seu Nome>Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

E se quiser pode usar o Badge também:

✅ Emojis

Status: Opcional

Vamos falar ainda sobre Emojis que estão bem na moda. Tem gente que não gosta, mas eles dão emoção ao texto e deixam o visual mais caprichado, porém não pode exagerar.

Fica legal colocar nos tópicos ou nas listas. Exemplo:

🏁 Tópicos

👉 Descrição do projeto

👉 Funcionalidades

👉 Deploy da Aplicação

👉 Pré-requisitos

👉 Como rodar a aplicação

Você pode pegar os emojis aqui ou aqui.

⚒️ Ferramentas:

Sites que dão dicas e inclusive um code/preview do README para seu projeto:

Conclusão

Escrever o README português ou inglês? Depende do objetivo do projeto, se for um portfólio e você está procurando emprego na gringa, tem que ser em inglês. Se for uma uma lib que pode ser usada por todo mundo, é interessante escrever em inglês, sua ferramenta vai ter mais alcance e relevância.

Se estiver começando no mundo da programação e não sabe inglês, faça em português mesmo, esse é o seu momento, mas estude inglês.

Dá para escrever em outros idiomas também, mas ai você pode pedir colaboração para isso, claro! Pode ter um README-en.md, ou seja internacionalizar o README e fornecer os links no README principal.

Se o projeto for algum portfólio para mostrar para alguma empresa aqui no Brasil pode ser em português mesmo. Depende do foco, momento e objetivo do projeto.

🎁 Template

Utilize esse template que preparamos para você construir o seu README. 💝

Para copiar a estrutura do README você tem que clicar no arquivo README.md e depois clicar na opção RAW, selecionar tudo, copiar e colar no seu editor preferido que suporte HTML e Markdown.

🔗 Links de README inspiradores:

➕ Mais sobre o assunto e outros aspectos interessantes:

Chegamos até o final desse artigo com o resultado das alterações que eu realizei no meu repositório.

O aprendizado é contínuo e sempre haverá um próximo nível!

Outro link interessante para encerrarmos esse tema é sobre a importância de ter um readme bem detalhado para esclarecer as funcionalidades do repositório.

Tomara que tenha gostado, aplauda o artigo! Até o próximo artigo e ótimos códigos.

--

--

Developer Frontend Web — Javascript | ReactJS https://linktr.ee/douglasabnovato

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store