Introdução ao markdown e aos READMEs
Olá, tudo certo? 👋
Hoje vou falar sobre o que é um README, o que é markdown, como escrever um README básico e por que você deveria aprender a sintaxe markdown e escrever READMEs. Bora?
O que é um README
Começando pelo começo, você provavelmente já viu projetos de outros desenvolvedores ou instalou um projeto, uma solução ou um jogo de origem duvidosa e se deparou com aquele arquivo README, README.txt ou README.md. Caso nunca tenha visto, tudo bem.
A tradução de read me é "leia me" e, resumidamente, um README é um arquivo que fica junto de um projeto e serve como um cartão de visita para o mesmo, contendo informações sobre o projeto como: objetivo, capacidade, instalação, documentação em geral, licença, etc.
Deu pra perceber a importância dos READMEs?
Um README geralmente é escrito em markdown, uma linguagem de marcação assim como o HTML. Dito isso, a forma mais comum desse arquivo é essa: README.md.
O que é markdown
Markdown é uma linguagem de marcação simplificada e de fácil uso. O primeiro processador de markdown foi o próprio Markdown feito pelo John Gruber com a linguagem de programação Perl. Ele tinha o objetivo de ser uma ferramenta de conversão de markdown para HTML.
Atualmente existem vários processadores Markdown e variações (ou supersets) da sintaxe, permitindo novas marcações e diferentes saídas. Por exemplo, de markdown para PDF.
Veja um resumo ou cheatsheet da sintaxe markdown:
# Isto é um título ou um h1 em HTML
## Isto é um subtítulo ou um h2 em HTML
### Você já entendeu... vai até o h6 ou ######
Isto é um parágrafo e a palavra **negrito** está em negrito, enquanto a palavra *itálico* está em itálico. ~~riscado~~ e [link](https://example.com).
- eu sou um item em uma lista desordenada
- eu sou outro item na lista desordenada
- eu sou mais um item
> Uma citação blablablablablabla
1. eu sou o primeiro item de uma lista ordenada
2. eu sou o segundo item
3. eu sou o terceiro!
---
Estou abaixo do divisor horizontal.
E o resultado:
Isto é um subtítulo ou um h2 em HTML
Você já entendeu... vai até o h6 ou
Isto é um parágrafo e a palavra negrito está em negrito, enquanto a palavra itálico está em itálico. riscado e link.
- eu sou um item em uma lista desordenada
- eu sou outro item na lista desordenada
- eu sou mais um item
Uma citação blablablablablabla
- eu sou o primeiro item de uma lista ordenada
- eu sou o segundo item
- eu sou o terceiro!
Estou abaixo do divisor horizontal.
Uma ótima referência para você se aprofundar é o Markdown Guide.
Por que aprender markdown e escrever READMEs
Escrever é algo muito importante na vida de um desenvolvedor. Todo projeto, decisão ou solução deveria ter uma documentação que defina, explique e/ou demonstre essas coisas.
Saber markdown facilita muito sua vida ao oferecer uma sintaxe simples e ser convertido em HTML, além de ser quase uma convenção (se não for) no quesito escrita técnica.
Resumo (tl;dr)
Markdown é uma linguagem de marcação que tem uma sintaxe simples, pode ser convertida para HTML e, com isso, ela pode ser usada para escrever textos formatados. Por ser fácil de ler e escrever, o markdown tem uma alta adoção na comunidade de desenvolvimento de software.
O README é como um cartão de visitas e serve para expor os detalhes mais relevantes de um projeto. Pode ser qualquer tipo de arquivo mas normalmente é escrito usando markdown, então um README geralmente tem a extensão .md para demonstrar isso.
Para conhecer a sintaxe, veja essa cheatsheet: Markdown Cheat Sheet.
Fun fact: esse texto foi escrito inteiramente em markdown e faz parte de uma série sobre READMEs :)
Obrigado por ler ❤
Também dá pra criar caixas pra marcar assim:
- [ ] Fazer artigo sobre Markdown
- [ ] Corrigir bug no sistema
- [x] Comentar sobre caixas de marcação
O resultado é esse:
- Fazer artigo sobre Markdown
- Corrigir bug no sistema
- Comentar sobre caixas de marcação
Boa introdução, comecei a utilizar mais ativamente o markdown graças ao Obsidian, fica aí a recomendação inclusive para quem busca uma aplicação para organizar anotações e outras funcionalidades mais.
Bem legal o conteúdo, queria complementar com 2 que eu uso muito. a code né, além de utilizar nos readmes, podemos utilizar essas sintaxes nos comentarios dos pull requests, ou seja colocando alguma dica ali em codigo .... se voce quiser colocar o code basta colocar as 3 aspas ''' (coloquei ' mas é `), porém se quiser especificar a linguagem basta colocar a extensão dela na frente ''' js ou ''' html
seu codigo vai ficar destacado como na linguagem mencionada.
Outro que acho interessante é o Details para colocar nos seus PR's
Que pode ser feito da seguinte maneira
<details><summary>Click aqui</summary>Tomou um susto né</details>
Eu uso bastante o details para colocar imagens, resultados, evidencias, para não ocupar muito a zona de leitura para ficar scrolando demais, se for do interesse da pessoa ela clica.
Um excelente editor que sempre uso para escrever meus readme.md: