Neste artigo irei mostrar como fazer um README.md bem feito dos seus projetos no GitHub. A extensão .md é um arquivo de markdown, que é uma linguagem de marcação (como o HTML), sendo utilizado para estilizar texto na internet. Diversas tags do HMTL também funcionam no markdown, e as duas possuem muita similaridade entre si.
Como já existem diversos artigos e documentações explicando sobre o markdown, vou direto ao ponto e mostrar as imagens do README pronto e a versão editável dele, diretamente pelo GitHub.
Nessas imagens, é possível ver alguns elementos que a maioria dos README dos iniciantes não contém, como os emoji, links para partes do texto, resumo com ícones, tabelas, links e imagens. Agora vamos a imagem do editor do próprio GitHub, mostrando os comandos para criar estas telas bonitas.
Aqui já podemos ver como foi feito o README e dá para ver que lembra bastante o HMTL. No começo é um pouco trabalhoso montar esta estrutura, mas depois de pronta, pode reaproveitas nos outros projetos para agilizar. Vou explicar o que fiz em cada uma das partes, dividindo em categorias.
Para começar, você pode criar um readme dentro da IDE de sua escolha ou através do GitHub, particularmente, eu prefiro criar pelo GitHub pois ele tem uma opção de pre –visualizar a edição. Para criar, basta clicar no balão azul que aparece quando criar um novo repositório, ou clicar no lápis no canto superior direito para editar (caso já tenha sido criado).
Na barra superior do editor do GitHub, vai ter as opções Edit new file (editar o arquivo), preview (função que gosto bastante, que permite ver o que está sendo feito). Do lado direito da barra superior, tem a parte de endentação, podendo se escolher entre espaços e tabs, espaço da endentação e separação da tela em blocos ou linhas. Agora, vamos ao código!
Cabeçalho
Para se escrever o título do artigo, eu optei por utilizar a tag <h1>, já que ela possui opção para centralizar o texto. Com o markdown, utiliza-se o comando # para título principal. Já os emoji são ativados com a tecla : (dois pontos), código do emoji e : (dois pontos) novamente para finalizar. Vou deixar aqui dois links que contém centenas de emojis que podem ser utilizados (uma alternativa é copiar a própria imagem do ícone, ao invés de inserir o código).
· Emoji 1: https://github.com/ikatyang/emoji-cheat-sheet#game
· Emoji 2: https://gist.github.com/rxaviers/7360908
Agora passando para o resumo com ícones, vamos começar colocando uma tag <p align=”center”>, que vai permitir alinhar todo o conteúdo. Cada um dos itens ficará dentro de uma tag <img>, o alt é um texto alternativo para SEO e o src é o que realmente importa, pois é ele que vai criar aqueles ícones bonitinhos. Para exibir a quantidade de linguagens utilizada no projeto insira o caminho:
src=”https://img.shields.io/github/languages/count/SEU-USUARIO/NOME-DO-REPOSITORIO”; para exibir o tamanho do projeto use src=https://img.shields.io/github/repo-size/SEU-USUARIO/NOME-DO-REPOSITORIO; para exibir a data do último commit use src=https://img.shields.io/github/last-commit/SEU-USUARIO/NOME-DO-REPOSITORIO; para exibir as issues (tarefas) use src=”https://img.shields.io/github/issues/SEU-USUARIO/NOME-DO-REPOSITORIO"; e, por fim, para exibir o tipo de licença do projeto use src=https://img.shields.io/badge/CAMINHO DA LICENÇA. Fazendo isso, terminamos nosso cabeçalho.
Corpo
O que coloquei na parte do conteúdo que difere foi o título foi uma tabela, links, imagens e pequenos comandos. Para colocar em negrito, coloque o texto entre ** *; em itálico, coloque o texto entre * *; em negrito e itálico, coloque o texto entre *_ _**.
Para colocar links, utilize o seguinte padrão vide exemplo:
[Udemy](https://www.udemy.com/course/java-curso-completo/). Entre os colchetes, coloque o texto que o usuário irá ver e entre os parênteses coloco o link que será redirecionado.
Para inserir imagens, o que faço é ir na aba New Issue do seu repositório e jogar a imagem que deseja utilizar ali dentro, em alguns segundo o GitHub vai hospedar sua imagem e gerar um link (como por exemplo, !tela-inicial). Basta então colar este link direto no readme para exibir a imagem.
Por fim, utilizei o recurso de tabelas. Para criar tabelas, utiliza-se as barras verticais | para separar as colunas e os hifens — para criar o cabeçalho. Segue o exemplo da própria documentação oficial do GitHub:
| Primeiro cabeçalho | Segundo cabeçalho |
| — — — — — — — — — — | — — — — — — — — — — |
| Célula de conteúdo | Célula de conteúdo |
| Célula de conteúdo | Célula de conteúdo |
No meu projeto, eu utilizei duas tabelas de 3 colunas para poder organizar melhor as imagens, o código que digitei para fazer a separação foi o seguinte:
Conclusão
Eu fiz aqui apenas um breve resumo de como eu crio os meus README e algumas funcionalidades que utilizei no exemplo. Mas existe muitas outras funcionalidades, além das que eu citei. Vou deixar aqui o link de outros artigos e documentação oficial que eu li para criar meus próprios readme personalizados, mas caso tenham alguma dúvida podem me perguntar e tento ajudar no que for possível!
· Artigo: https://medium.com/@raullesteves/github-como-fazer-um-readme-md-bonit%C3%A3o-c85c8f154f8
· Documentação: https://docs.github.com/pt/github/writing-on-github/basic-writing-and-formatting-syntax
· Documentação 2: https://docs.github.com/pt/github/writing-on-github/working-with-advanced-formatting
Top comments (0)