Loading repository data…
Loading repository data…
mende1 / repository
:newspaper: O guia definitivo de Markdown e a importância de um bom README.md em seu repositório, para iniciantes.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
Com a popularização do GitHub e com o surgimento de uma leva de novos desenvolvedores, a demanda por aprender Markdown aumentou significativamente. Markdown é uma linguagem de marcação, parecida com o HTML.
Ela é muito utilizada na criação dos famosos READMEs para seus respectivos repositórios no GitHub, podendo deixá-los mais 'apresentáveis'. Então, é por esse motivo que trago aqui um guia simples porém definitivo para aprender o tão popular Markdown e utilizá-lo no README do seu projeto.
Todo projeto no GitHub terá seus códigos, seus arquivos e suas pastas. Um projeto bem estruturado precisa informar ao leitor a razão de existência do projeto, qual sua finalidade, os recursos que oferece, em qual ou quais linguagens foi escrito, as ferramentas utilizadas, como contribuir e várias outras informações necessárias que acharem pertinentes. E para isso existe um arquivinho bem simples chamado 'README.md' ou 'readme.md' em todo repositório minimamente organizado no GitHub. Perceba que o arquivo possui o sufixo '.md', essa é a extensão dos arquivos Markdown. Ao criar o README.md em seu repositório, ao rolar um pouco para baixo a página inicial, todo o conteúdo do README.md formatado em Markdown será exibido. Ele deverá conter todas as informações do projeto. Para ver o conteúdo sem formatação, procure um ícone de um lápis, ou até clique no arquivo em si README.md, assim você será encaminhado para a edição do arquivo.
Fica claro aqui que são todas opcionais, cabe a você desenvolvedor analisar e escolher quais colocar em seu repositório. Lembrando que nem todos os pontos a seguir cabem em todos os repositórios, depende do que ele se trata, se é um jogo, um programa, um código-fonte de um website. Saiba escolher o que colocar.
Uma breve apresentação sobre o que é o seu projeto, o que ele faz, e algumas informações úteis para serem ditas inicialmente.
É interessante ter um índice com os links para os tópicos que vão ser abordados em seu texto, assim como o índice deste tutorial.
Se seu projeto visa a aprendizagem, o seu próprio estudo ou até base para estudos de outras pessoas, é interessante colocar quais habilidades são requeridas para estudar/rodar o seu código, ou habilidades que vão ser adquiridas se seguirem os seus estudos.
Se você tem um programa que faz alguma coisa, um jogo, um código em determinada linguagem, é interessante adicionar a informação de como executar seus códigos, quais programas o usuário precisa no computador, comando para executar os códigos, algumas informações de quais arquivos precisa ter, entre diversos outros.
Se seu projeto é OpenSource, é natural que outros programadores desejem melhorar algum código dele, adicionando novos recursos, corrigindo algum bug, implementando alguma tecnologia, entre diversos outros. Para isso, ele deverá fazer pulls requests em seu código, seria muito interessante implementar algumas informações de como contribuir com o projeto, como fazer um Fork, como fazer o pull request, e até algumas preferências pessoais suas de como você quer o pull request.
É interessante também em alguns casos concluir com os créditos do repositório ou até mesmo da licença utilizada nele.
Note que não são todos os pontos a colocar, tão pouco são obrigatórios, pensei apenas em ajudar os iniciantes que estão criando seus repositórios no momento, e alguns pontos que são muito importantes para projetos simples. Claro que projetos mais avançados requerem muito mais pontos a serem colocados, e depende muito de um para outro. O foco destas dicas é pensando nos projetos mais básicos e iniciantes.
Inicialmente temos os 'Headings', ou Títulos. Eles se apresentam hierarquicamente variando o tamanho da fonte. Ou seja, o título número 1 é mais importante que o título número 2, que por sua vez é mais importante que o número 3, e assim por diante. Existem 6 títulos, que vão do título 1 (mais importante e por conseguinte maior e mais destacado) até o título 6 (menos importante e por conseguinte menor e menos destacado).
A sintaxe é simples:
# Título 1
## Título 2
### Título 3
#### Título 4
##### Título 5
###### Título 6
Varia de acordo com o número de '#'. Exemplos:
Você pode adicionar ênfase ao seu texto, como por exemplo o negrito, o itálico, ou até mesmo negrito e itálico. Lembre-se que além da aparência do seu texto, existe a semântica a ser seguida. Textos em negrito devem ser lidos com força, intensidade, e o itálico significa uma ênfase maior.
Sintaxe do negrito:
Este é **negrito**
This is __strong__
Sintaxe do itálico:
Este é *itálico*
This is _italic_
Sintaxe do negrito e itálico:
**_strong and em_**
Sintaxe do texto riscado:
~~riscado~~
Você pode adicionar linhas horizontais para deixar o texto mais organizado e apresentável. Usando três hifens, três asteriscos ou três underscore:
Hifens
---
Asteriscos
***
Underscore
___
Learning Center:
Hifens
Asteriscos
Underscore
Para criar uma citação em bloco, adicione um '>' na frente de um parágrafo.
As citações em bloco podem conter vários parágrafos. Adicione um '>' nas linhas em branco entre os parágrafos.
Sintaxe:
Para citações em uma linha:
> Esta é uma citação
Em várias linhas:
> Citação 1
>
> Citação 2
Resultado:
Para citações em uma linha:
Esta é uma citação
Em várias linhas:
Citação 1
Citação 2
As citações em bloco podem ser aninhadas. Adicione um '>>' na frente do parágrafo que você deseja aninhar. Por exemplo:
> Citação 1
>
>> Citação 2
E assim temos:
Citação 1
Citação 2
As citações de bloco podem conter outros elementos no formato Markdown. Nem todos os elementos podem ser usados, você precisará experimentar para ver quais funcionam. Exemplo:
> ##### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
> *Everything* is going **well**.
Resultado:
The quarterly results look great!
- Revenue was off the chart.
- Profits were higher than ever.
Everything is going well.
Você pode organizar listas, podendo ser ordenadas ou não.
Listas Ordenadas
Usando (número)(ponto) você pode ordenar as listas numericamente, como por exemplo:
1. Primeiro
2. Segundo
3. Terceiro
4. Quarto
Vai gerar o seguinte resultado:
Os itens da lista de aninhamento
Para aninhar itens de linha em uma lista ordenada, recue os itens quatro espaços ou uma guia.
1. Primeiro item
2. Segundo item
3. Terceiro item
1. Indentado item
2. Indentado item
4. Quarto item
Irá gerar:
Listas não Ordenadas
Para criar uma lista não ordenada, adicione traços (-), asteriscos (*) ou sinais de adição (+) na frente de itens de linha.
- Exemplo 1
* Exemplo 2
+ Exemplo 3
Vai gerar:
Lista de tarefas
Podemos criar também uma lista de tarefas, com a CheckBox preenchida ou não. Vejamos o exemplo:
- [ ] Esta é uma CheckBox não marcada
- [x] Esta é uma CheckBox marcada
Learning Center:
É possível exibir um código sem que ele seja formatado em Markdown, ou seja, ele será exibido exatamente como foi escrito, sem formatação Markdown. Existe o trecho simples, composto apenas por uma linha. Usamos uma crase para abrir e outra para fechar o trecho a ser destacado como trecho de código:
` este é um exemplo `
Resultado:
este é um exemplo
E também há a demarcação de bloco de código composto por várias linhas. Para isso utilize três crases ( ´´´ ) ou três tils ( ~~~ ) para abrir e três para fechar o bloco, desta forma:
```
Este é nosso
Querido Exemplo
**Teste**
Nota que não irá formatar o negrito!
```
Resultado:
Este é nosso
Querido Exemplo
**Teste**
Note que o trecho não ficará em negrito!
Para se ativar o realce da sintaxe do código, deve-se especificar em qual linguagem ele foi escrito logo após os três primeiros tils ou crases. Isso irá realçar a sintaxe, melhorando assim a legibilidade do código.
Por exemplo:
~~~python
s = "Sintaxe do Python"
print s
~~~
s = "Sintaxe do Python"
print s
Para saber quais linguagens são suportadas por este mecanismo, clique aqui e veja a listagem do Pygments.
Nota: Para aninhar um código dentro do outro, assim como eu fiz de exemplo para vocês: Abra o primeiro trecho de código com as três crases, e feche de imediato. Dentro desse código use a indentação de 4 espaços, e assim poderá abrir outro código sem formatar.
Para embutir links nas palavras, coloque-as entre colchetes [ ] e entre parênteses ( ) a URL. Por exemplo:
Clique [aqui](https://github.com) para acessar a página do GitHub.
Resultado: Clique aqui para acessar a página do GitHub.
Lembre-se que você poderá criar links para outros repositórios no Github, ou para arquivos no repositório local, especificando opcionalmente a posição na página do arquivo. Por exemplo, clique aqui para acessar o título 'Sintaxe' neste mesmo arquivo. Tais recursos deixam seu README bem mais apresentável e interativo. Para exibir links contendo apenas a URL escreva o link entre '< >'. Exemplo: https://google.com.br
A sintaxe é um pouco parecida com a anterior, apenas adic