DEV Community

Kauê Fraga Rodrigues
Kauê Fraga Rodrigues

Posted on • Updated on

Personalizando o README do seu projeto

Opa, tudo tranquilo?

Continuando a série sobre READMEs, agora vamos falar da personalização 🤩

Vamos usar markdown para customizar o README do seu projeto com seções, frases, ícones/insígnias, etc. Se você não tem ideia do que é markdown e README, recomendo ler o primeiro artigo desta série, Introdução ao markdown e aos READMES.

Estruturando o README

Pense no modo que você quer expor as informações do seu projeto. Defina uma hierarquia e use vários identificadores (seções, negrito, código...).

Depois de fazer alguns projetos e espiar um bocado de projetos alheios, eu normalmente estruturo meu projeto da seguinte forma:

  1. Título ou nome do projeto
  2. Descrição
  3. Funcionalidades
  4. Como instalar/rodar/usar
  5. Licença

É isso! Simples, não?

Você pode adicionar mais informações, mas eu acredito que essas sejam essenciais.

Se você não sabe o que adicionar, pense em quais informações são importantes para o projeto. Eu tenho algumas sugestões:

  • documente as tecnologias e a escolha delas
  • descreva a arquitetura, os padrões de projetos e o porquê dessas decisões
  • dedique uma seção a sua API (interna ou não)
  • liste as variáveis de ambiente necessárias para executar o projeto
  • exemplifique a utilização do projeto (código ou imagem/vídeo)
  • explique os passos necessários para contribuir
  • mencione os contribuidores
  • diga se tem testes e como roda-los

Estilizando essas informações com markdown

Fique atento, em algumas partes eu vou adicionar só a opção discutida (incremental mesmo) e em outras eu vou reescrever boa parte do código já mostrado porque alguma coisinha ali foi alterada.

Especifique o título

Dica: tente criar um nome explicativo e memorável para o seu projeto, por mais difícil que isso seja 😅

# Título do projeto
Enter fullscreen mode Exit fullscreen mode

Centralizado:

<h1 align='center'>Nome do projeto</h1>
Enter fullscreen mode Exit fullscreen mode

Não é possível centralizar com markdown, por isso usamos HTML.

Adicione insígnias legais ao seu projeto

Veja no site shields.io. Segue as que eu mais uso:

  • Linguagem mais utilizada
  • Último commit
  • Palavras/frase estática
  • Licença
  • Downloads (GitHub releases, crates.io, npm...)
  • Versão mais recente
# Título do projeto

![Linguagem mais utilizada](https://img.shields.io/github/languages/top/:nomedeusuario/:nomedorepositorio)
![Último commit](https://img.shields.io/github/last-commit/:nomedeusuario/:nomedorepositorio)
![README bem legal](https://img.shields.io/badge/readme-bem_legal-8A2BE2)
Enter fullscreen mode Exit fullscreen mode

Centralizado:

<div align='center'>
    <h1>Nome do projeto</h1>
    <img src='https://img.shields.io/github/languages/top/:nomedeusuario/:nomedorepositorio' alt='Linguagem mais utilizada' />
    <img src='https://img.shields.io/github/last-commit/:nomedeusuario/:nomedorepositorio' alt='Último commit' />
    <img src='https://img.shields.io/badge/readme-bem_legal-8A2BE2' alt='README bem legal' />
</div>
Enter fullscreen mode Exit fullscreen mode

Lembre-se de trocar as informações :nomedeusuario e :nomedorepositorio.

Coloque uma descrição

# Título do projeto

![Linguagem mais utilizada](https://img.shields.io/github/languages/top/:nomedeusuario/:nomedorepositorio)
![Último commit](https://img.shields.io/github/last-commit/:nomedeusuario/:nomedorepositorio)
![README bem legal](https://img.shields.io/badge/readme-bem_legal-8A2BE2)

Esta é a descrição do meu projeto super legal.
Enter fullscreen mode Exit fullscreen mode

Descrição como citação:

> Esta é a descrição do meu projeto super legal.
Enter fullscreen mode Exit fullscreen mode

Centralizado:

<div align='center'>
    <h1>Nome do projeto</h1>
    <p>Esta é a descrição do meu projeto super legal.</p>
    <img src='https://img.shields.io/github/languages/top/:nomedeusuario/:nomedorepositorio' alt='Linguagem mais utilizada' />
    <img src='https://img.shields.io/github/last-commit/:nomedeusuario/:nomedorepositorio' alt='Último commit' />
    <img src='https://img.shields.io/badge/readme-bem_legal-8A2BE2' alt='README bem legal' />
</div>
Enter fullscreen mode Exit fullscreen mode

Diga quais são as funcionalidades

As funcionalidades podem ser capacidades, rotas ou o que seu projeto fizer.

### Funcionalidades

- Este projeto é capaz de automatizar um processo muito chato
- Este projeto é muito performático
- Este projeto é amigável e intuitivo
Enter fullscreen mode Exit fullscreen mode
## Features

- [x] Este projeto é capaz de receber requisições e responder
- [x] Este projeto é capaz de lidar com requisições simultaneamente, graças ao controle de concorrência implementado
- [ ] Este projeto pode teletransportar uma pessoa para qualquer lugar do planeta a qualquer momento
Enter fullscreen mode Exit fullscreen mode

Perceba a alteração das palavras (funcionalidades e features), nível da seção (h3 e h2) e lista (não-marcada e marcada). Faça como quiser.

Como instalar e rodar

Aqui você precisa descrever o processo de instalação e execução/utilização do seu projeto.

## Como instalar e rodar

1. Clone o repositório
2. Instale as dependências
3. Execute o comando x

<----->bash
git clone https://github.com/usuario/repositorio.git
cd repositorio

npm i
go mod download
cargo build

npm run start
go run cmd/main.go
cargo run src/main.rs
<----->

Obs.: uma observação muito interessante.
Enter fullscreen mode Exit fullscreen mode

Substitua esses <-----> por crases triplas (bloco de código).

Instrua contribuidores

Uma seção dedicada a como contribuir pode ser muito útil. Detalhe o processo de contribuição.

## Contribuindo

Sinta-se livre para contribuir, criar uma issue para reportar um bug, sugerir um alteração na API, uma melhoria ou uma feature. Fique à vontade.

### Como contribuir

1. Faça um fork desse repositório
2. Clone seu fork na sua máquina
3. Faça alterações, commit e dê push
4. Abra um pull request (escreva uma mensagem descritiva sobre o que você alterou)
Enter fullscreen mode Exit fullscreen mode

Mencionar os seus contribuidores e declarar sua gratidão é bacana também. Coloque o ícone dos seus contribuidores.

### Contribuidores

Meus agradecimentos a essas pessoas incríveis:

[![notshwuy GitHub profile picture](https://github.com/notshwuy.png?size=50)](https://github.com/notshwuy)
[![FelipeMCassiano GitHub profile picture](https://github.com/FelipeMCassiano.png?size=50)](https://github.com/FelipeMCassiano)
Enter fullscreen mode Exit fullscreen mode

Exponha a licença

## Licença

Este projeto está sob a licença y - Veja a [LICENÇA](https://github.com/usuario/repositorio/blob/main/LICENSE) para mais informações.
Enter fullscreen mode Exit fullscreen mode

Resultado final

Veja como ficou o README copiando e colando direto daqui:

Resultado final

Basicamente é isso. Lembra que o README é um "cartão de visitas" para o seu projeto? O que você quer mostrar aos seus visitantes? Você deve montar seu README pensando nas informações que são relevantes para o seu projeto. A partir disso, escreva e refine ao longo do tempo.

Fun fact: dependendo do lugar que você pretende colocar seu README (GitHub, GitLab, Bitbucket...) pode existir um superset do markdown como diz o Markdown Guide em extended syntax, que adiciona marcações e melhora o comportamento de algumas existentes.

Se você usa o Visual Studio Code para escrever seus READMEs, eu tenho extensões para recomendar:

Também selecionei alguns dos meus melhores READMEs para você ter uma ideia de como eu faço:

Obrigado por ler 💜

Top comments (2)

Collapse
 
jotavetech profile image
João Vitor

Seguindo aqui pra criar o readme do meu projeto

Collapse
 
clintonrocha98 profile image
Clinton Rocha

Outro artigo muito legal, lembrando que essas dicas também servem para produzir artigos aqui no Dev.to 😁