Value your project (Valorize o seu projeto).
Markdown é uma linguagem de marcação criada por Jonh Gruber e Aaron Swartz. Markdown converte seu texto em HTML válido.
A ideia desse projeto, é tentar passar o pouco aprendido para ajudar a comunidade no apredizado dessa linguagem de marcação que é tão importante para valorizar os nossos projetos.
O títulos são muito importantes para que possamos organizar os nossos documentos, e no Markdown não é diferente.
Para nos auxiliar na criação de uma documentação elegante, assim como o HTML o Markdown fornece uma 6 herarquia de títulos similares ao h1 a h6 no HTML.
Para criarmos um título basta utilizarmos # Título (hashtag + espaço + Título), ao qual conforme quantidade de # que usamos corresponde a herarquia de nosso título, conforme example abaixo.
# Título 1 (h1)
## Título 2 (h2)
### Título 3 (h3)
#### Título 4 (h4)
##### Título 5 (h5)
###### Título 6 (h6)- Resultado
Podemos adicionar a nossa # opcionalmente no final de cada título # Título #, mais isso seria algo mais estético.
Somente para o "h1" e "h2" podemos adicionar conforme exemplo abaixo, porém pouco usado.
Título 1 (h1)
=
Título 2 (h2)
-Para o Título 1 (h1) na próxima linha subsequente adicionamos o sinal de igual
=, já para o nosso Título 2 (h2) na linha subsequente adicionamos o sinal de menos-.
Adicionarmos páragrafos no nosso Markdown não poderia ser mais fácil, basta apenas adicionarmos o texto que quermos e pronto.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.- Resultado
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Porém a única coisa que devemos nos preocupar é que se queremos quebrar linha no nosso texto não basta apenas adicionarmos Enter ao código, mais sim adicionarmos dois espaços em branco na linha que queremos quebrar.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. - Resultado
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Outra coisa que podemos querer fazer, é adicionarmos um espaço entre um páragrafo e outro, e para isso devemos apenas adicionar dois Enter no começo do texto que queremos quebrar.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.- Resultado
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ênfase é um recurso muito importante, quando queremos destacar algo, ou fazer com que o nosso leitor dê uma maior atenção para aquela palavra um trecho de texto.
No Markdown temos várias opções que podemos utilizar para dar ênfase, ou para fazer alguma citação no nosso código, sendo elas.
Podemos usar essas opções individualmente, ou em conjunto para alcançarmos um resultado ainda mais legal.
Para adicionarmos negrito temos duas opções, ou usamos dois asteriscos ** ou também podemos utilizarmos de dois underline __. Ambos devem ser colocados no começo e no final do trecho que queremos destacar.
**Lorem**, ipsum dolor sit amet, consectetur.
__Lorem__, ipsum dolor sit amet, consectetur.- Resultado
Lorem, ipsum dolor sit amet, consectetur.
Lorem, ipsum dolor sit amet, consectetur.
Assim como no negrito, no itálico também temos duas opções para adicionarmos, podendo usar um asteriscos * ou também podemos usar de um underline _. Ambos devem ser colocados no começo e no final do trecho que queremos destacar.
*Lorem*, ipsum dolor sit amet, consectetur.
_Lorem_, ipsum dolor sit amet, consectetur.- Resultado
Lorem, ipsum dolor sit amet, consectetur.
Lorem, ipsum dolor sit amet, consectetur.
Para adicionarmos uma palavra ou um trecho de um texto como tachado (riscado) devemos utilizar dois acentos til ~~ no começo e no final do trecho que queremos destacar.
~~Lorem~~, ipsum dolor sit amet, consectetur.- Resultado
Lorem, ipsum dolor sit amet, consectetur.
Caso queremos realizar alguma citação em nosso Markdown podemos utilizar o sinal de maior que > no começo do parágrafo seguido de um espaço para que possamos destaca-lo.
> A vingança nunca é plena malta a alma e envenena- Resultado
A vingança nunca é plena malta a alma e envenena.
Para que possamos adicionar negrito e itálico em uma mesma palavra por exemplo, podemos usar três asteriscos *** ou três underlines ___, porém o mais utilizado pela comunidade são as combinações **_Lorem_** ou __*Lorem*__.
Linhas horizontais são muito uteis quando queremos realizar alguma separação dos conteúdos para facilitar a leitura. No Markdown temos duas opções de fazermos isso, ao qual ambas também possuem pequenas váriações.
***
A vingança nunca é plena malta a alma e envenena
---- Resultado
A vingança nunca é plena malta a alma e envenena
Podemos utilizar de três asteriscos *** ou de três sinais de menos ---. Uma variação que podemos usar é adicionarmos espaços entre os asteriscos * * * ou entre os sinais de menos - - -.
Outra coisa que podemos fazer também caso desejamos é completar toda a linha com asteriscos ou sinais de menos, porém isso é algo totalmente opcional e ao mesmo tempo gera apenas uma estética para o seu arquivo.
Lembrando que possamos adicionar nossa linha vertical é necessário termos ou três asteriscos ou três sinais de menos com ou sem espaço entre eles.
Listas não ordenadas é um recurso muito importante, pois permite criarmos tópicos de textos para uma melhor exemplificação sobre determinados assuntos.
Para criarmos listas não ordenadas no Markdown é muito simples do que criamos no HTML. Para isso temos duas opções, ou usamos o asterisco * ou podemos usar também o sinal de menos -, ambos seguidos por espaço entre os itens.
Produtos
* Item 01
* Item 02
* Item 03- Resultado
Produtos
- Item 01
- Item 02
- Item 03
Como informado anteriormente também podemos criar utilizando o sinal de menos -.
Produtos
- Item 01
- Item 02
- Item 03- Resultado
Produtos
- Item 01
- Item 02
- Item 03
Caso desejamos criar uma lista não ordenada com subitens também podemos e de maneira simples e fácil, basta na frente de cada subitem adicionarmos um TAB ou dois espaços.
Sumário
* Item 01
* SubItem 01
* SubItem 02
* Item 02
* SubItem 02
* Item 03- Resultado
Sumário
- Item 01
- SubItem 01
- SubItem 02
- Item 02
- Item 03
Assim com as listas não ordenadas, as listas ordenadas são muito importantes para exemplicação de nossos conteúdos. Da mesma maneira definir listar ordenadas no Markdown é algo muito simples.
Para essa criação necessitamos apenas informar o número a partir de qual queremos que nossa lista inicie seguida do ponto . e do espaço.
Sumário
1. Item 01
2. Item 02
3. Item 03- Resultado
Sumário
- Item 01
- Item 02
- Item 03
Podemos facilmente iniciarmos a nossa contagem a partir de outro número e não necessariamente do número 1.
Sumário
8. Item 01
9. Item 02
10. Item 03- Resultado
Sumário
- Item 01
- Item 02
- Item 03
Mesmo sendo algo extremamente simples de implementarmos as listas ordenadas possuem alguns particularidades.
Caso informamos os mesmos números para todos os itens, a lista automaticamente segue a sequência de forma crescente.
Sumário
1. Item 01
1. Item 02
1. Item 03- Resultado
Sumário
- Item 01
- Item 02
- Item 03
Caso também informamos os itens de maneira desordenada, a lista ordenada irá gerar uma nova sequência baseada no primeiro item da lista.
Sumário
8. Item 01
5. Item 02
3. Item 03- Resultado
Sumário
- Item 01
- Item 02
- Item 03
Com base nessas informações você deve estar se perguntando e caso eu queira fazer uma lista ordenada com a sequência que eu passar para ela? A solução também é bem simples basta colocarmos o número desejado seguido de um caracter de escape e do ponto \. e posteriormente do espaço.
Campeões da Copa Mundial
1994\. Brasil
1998\. França
2002\. Brasil - Resultado
Campeões da Copa Mundial
1994. Brasil
1998. França
2002. Brasil
Algo que com certeza não deve faltar em uma boa documentação, são os links pois eles são muito uteis ou para facilitar na navegação durante a leitura do usuário ou para fornecer mais informações importantes para compreensão da mensagem, podendo ser um link para uma guia de instalação ou para outra documentação de outro projeto.
Para criarmos um link no Markdown basta informarmos dentro colchetes [] o nome que será informado para o usuário de entre parênteses () informamos o link.
[Instalação GIT](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)- Resultado
Algo que podemos adicionarmos aos nossos links para melhorar a usabilidade são os nomes que aparecerão quando o cursor do mouse estiver por cima do link, para isso basta dentro dos parênteses () e posteriormente ao link informado, adicionarmos um espaço e entre aspas duplas "" informamos o texto desejado.
[Instalação GIT](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git "Instalação GIT")- Resultado
Outra coisa que podemos fazer em nossos links é criarmos uma váriavel contendo a url do mesmo, para isso basta dentro de colchetes [] informar o nome da váriavel depois adicionarmos dois pontos : e o valor da mesma.
Nessa abordagem a definição de um link muda um pouco ao qual informaremos agora entre colchetes [] o nome para o nosso link e novamente dentro dos colchetes [] informamos o nome da nossa variável.
[Instalação GIT][git-url]
[git-url]:https://git-scm.com/book/en/v2/Getting-Started-Installing-Git- Resultado
Algo que enriquece bastante uma documentação sem dúvida são as imagens, podendo ser uma captura de tela que mostra aquele seu layout bacana. Como se dizem uma imagem vale mais que mil palavras.
O processo de inserção de imagens no Markdown é bastante semelhante a crianção de um Link diferenciando apenas que para as imagens temos que adicionar no começo um sinal de exclamação !.
- Resultado
Assim com nos Links também podemos usar uma váriavel para armazenar o endereço da nossa imagem.
![Seu Madruga][vinganca-img]
[vinganca-img]:images/vinganca.jpg- Resultado
Algo que podemos adicionar em nossas imagens são os links, ao qual permite que o usuário navegue para a mesma após clicar sobre. E para isso devemos apenas envolver a nossa declaração da imagem  ou ![nome][variavel-endereco] dentro dos colchetes [], e posteriormente dentro dos meus parênteses () ou colchetes [] caso estejamos usando váriaveis para nosso link informamos o endereço de destino [](url).
[](https://github.com/zander-br/markdown-course/blob/master/images/vinganca.jpg)- Resultado
A essa altura você já deve estar se perguntando, mais como faço para alterar o tamanho da minha imagem? Nesse caso o Markdown não possui suporte para esse tipo de situação, porém como solução podemos fazer uso da tag img do HTML, conforme exemplo abaixo.
<img src="images/vinganca.jpg" width="100px;" alt="Seu Madruga"/>- Resultado
Outra coisa que temos disponível no Markdown e nos auxilia bastante nas nossas documentações são as tabelas, com elas podemos demostrar o retorno de alguma informação, organizar as dependências do projetos com links para seus respectivos repositórios e por aí vai.
E para criarmos as nossas tabelas no Markdown não poderia ser mais simples basta encapsularmos nossos valores das colunas dentro de um pipe | da seguinte forma | coluna | colocando sempre um espaço entre os pipes e o conteúdo. Uma pequena atenção que precisamos ter é que no caso dos cabeçalhos da tabela na próxima linha subsequente devemos adicionar um sinal de menos - representando as colunas. Com o exemplo tudo irá ficar mais simples.
| Nome | Idade |
| - | - |
| Anderson | 30 |- Resultado
| Nome | Idade |
|---|---|
| Anderson | 30 |
Opcionalmente podemos alinharmos o pipe | no nosso documento, porém isso não gera resultado diferente na documentação, apenas algo estético.
| Nome | Idade |
| -------- | ----- |
| Anderson | 30 |- Resultado
| Nome | Idade |
|---|---|
| Anderson | 30 |
Mais como fica em tabelas maiores? Montei um examplo um pouco maior para demostrar o resultado.
| Nome | Idade | Profissão |
| ---- | ----- | --------- |
| Anderson Santos | 30 | Programador |
| Alvo Dumbledore | 150 | Diretor |
| McGonagall | 70 | Professora |- Resultado
| Nome | Idade | Profissão |
|---|---|---|
| Anderson Santos | 30 | Programador |
| Alvo Dumbledore | 150 | Diretor |
| McGonagall | 70 | Professora |
Caso seja necessário também, podemos utilizar alinhamentos em nossas tabelas, e para fazermos isso basta adicionarmos sinal de dois pontos : na linha que vem logo após o cabeçalho e juntamente com o sinal de menos -.
Para alinhamentos a esquerda basta adicionarmos o sinal de dois pontos no lado esquerdo do sinal de menos :-, para alinhamentos a direita posicionamentos a direita -: e para alinhamentos ao centro colocamos o sinal de menos entre o sinal de dois pontos :-:. Simples assim, mais de qualquer forma vamos demostrar no exemplo abaixo.
| Nome (esquerda) | Idade (centro) | Profissão (direita) |
| :-------------- | :------------: | ------------------: |
| Anderson Santos | 30 | Programador |
| Alvo Dumbledore | 150 | Diretor |
| McGonagall | 70 | Professora |- Resultado
| Nome (esquerda) | Idade (centro) | Profissão (direita) |
|---|---|---|
| Anderson Santos | 30 | Programador |
| Alvo Dumbledore | 150 | Diretor |
| McGonagall | 70 | Professora |
Chegamos agora em um ponto que é extremante importante para uma boa documentação, principamente para bibliotecas, projetos de código aberto, e sem sombra de dúvida estamos falando dos exemplos de códigos para ajudar aquele nosso amiguinho.
No Markdown demos duas forma de demostrar nosso código, podendo ser inline, ou seja, na própria linha que estamos escrevendo, ou criando um bloco de códigos. Também temos um pequeno plus que são o Syntax Highlighting essa opção sem dúvida é a cereja do bolo.
Como já comentado anteriormente a inserção de códigos inline (na linha) é muito importante quando estamos decorrendo sobre um determinado assunto e queremos informar um pequeno trecho de código, ou uma chamada de um metódo ou função.
Para que possamos adicionar um código inline no Markdown basta que informamos o mesmo dentro do acento de grave (`) representado aqui dentro dos parânteses.
Passe o `username` e `password` como parâmetros para a função `login()`.- Resultado
Passe o username e password como parâmetros para a função login().
Em linguagens como por exemplo o JavaScript temos uma funcionalidade nas strings chamado Template string que faz uso do acento grave para realizar concatenação de textos.
Nesse caso devemos fazer o escape de caracteres para que possamos conseguir o mesmo resultado.
``const message = `My name is ${name}`;``- Resultado
const message = `My name is ${name}`;
O exemplo acima foi desenvolvido utilizando a linguagem JavaScript assim como os exemplos subsequentes.
Muitas vezes o que queremos fazer é mostrar uma grande qualidade de código, para que façamos isso também é muito simples, e temos mais que uma opção para alcançar o mesmo resultado.
A primeira opção é na frente do bloco de código que queremos adicionar, inserirmos dois TABs ou quatro espaços.
// login.js
const username = 'zander-br';
const password = 'secret';
login(username, password);- Resultado
// login.js
const username = 'zander-br';
const password = 'secret';
login(username, password);
Porém a forma mais usada pela comunidade é o uso de três assentos graves antes do código (uma linha acima) e depois do código (uma linha abaixo).
```
// login.js
const username = 'zander-br';
const password = 'secret';
login(username, password);
```
- Resultado
// login.js
const username = 'zander-br';
const password = 'secret';
login(username, password);
Como comentado anteriormente, chegamos agora a cereja do bolo, pois o uso de Syntax Highlighting não somente cria para nós uma bloco de código como também realça o mesmo com cores.
// login.js
const username = 'zander-br';
const password = 'secret';
login(username, password);O que achou desse código? Legal né? Você deve estar se perguntando qual a mágica que foi usada aqui, ou então afirmando... Isso deve ser muito dificil de fazer.
Se se eu falar que tudo que você deve fazer é informar na frente dos três primeiros acentos graves o nome da linguagem e caixa baixa.
```javascript
// login.js
const username = 'zander-br';
const password = 'secret';
login(username, password);
```
- Resultado
// login.js
const username = 'zander-br';
const password = 'secret';
login(username, password);Nesse momento você deve estar falando, mais isso funciona apenas para javascript... Então o que acha desse trecho de código em Ruby.
```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```
- Resultado
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_htmlMuito legal né? Porém você deve informar apenas uma liguagem por blocos de códigos. Outra dica interessante é que no caso do JavaScript podemos usar javascript ou simplesmente js.
E para finalizar vou dar algumas dicas sobre o uso de Markdown no GitHub que irá turbinar ainda mais o seus conhecimentos e também ajudar ainda mais nas suas contribuições.
No GitHub podemos fazer uso de emojis 😍 é isso mesmo que você entendeu você pode adicionar emojis tanto em mensagens de commits, quanto no seu README.md e também nas Issues do GitHub.
Para isso basta adicionar entre dois pontos : o nome do emoji que deseja adicionar. E para facilitar a sua vida estarei deixando aqui uma lista com todos esses emojis Emoji Cheat Sheet.
Estou estou :heart_eyes: esse conteúdo, simplesmente ficou show! :relaxed:- Resultado
Estou amando 😍 esse conteúdo, simplesmente ficou show!
Outra coisa que podemos fazer é adicionarmos uma lista de Todo das pendências ou coisas que precisam ser desenvolvidas em uma issues. Para isso basta adicionar dois colchetes [] e entre eles adicionar um espaço. Caso o item tenha sido finalizado basta adiconar uma letra x.
Curso de markdown no Github
* [x] Estudar sobre markdown :books:
* [ ] Deixar uma estrela no repositório :star:
* [ ] Indicar para os meus amigos :family:- Resultado
Curso de markdown no Github
- Estudar sobre markdown 📚
- Deixar uma estrela no repositório ⭐
- Indicar para os meus amigos 👪
Algo que não foi mencionado durante esse conteúdo por não se tratar de algo nativo no Markdown, porém que muitas vezes acabamos querendo usar para deixar as nossas documentações mais bonitas e atrativas, são os alinhamentos de conteúdos.
No Markdown não temos maneira de fazermos o aninhamento dos conteúdos, porém como mencionado inicialmente na introdução do conteúdo, o Markdown converte o seu texto em HTML válido, ou seja, assim como na seção de Imagens podemos fazer uso de tags HTML para extender as funcionalidades do Markdown.
Por isso para conseguirmos alinharmos nossos conteúdos em nossas documentações podemos HTML para isso conforme exemplos abaixo.
<p align="center">
<img src="images/vinganca.jpg" width="100px;" alt="Seu Madruga"/>
</p>
<p align="center">"Eu prefiro morrer que perder a vida"</p>- Resultado
"Eu prefiro morrer que perder a vida"
Acima temos o alinhamento de conteúdos ao centro, nota que não usamos uma div pois o alinhamento na div não funciona no GitHub.
<p align="right">
<img src="images/vinganca.jpg" width="100px;" alt="Seu Madruga"/>
</p>
<p align="right">"Eu prefiro morrer que perder a vida"</p>- Resultado
"Eu prefiro morrer que perder a vida"
Da mesma forma também podemos fazer o alinhamento dos conteúdos a direita, mudando apenas a propriedade align=right. O alinhamento a esquerda é padrão do Markdown então podemos continuar usando nessas situações.
Como informado no começo desse conteúdo, a ideia desse repositório surgiu para ajudar na fixação dos conteúdos que eu estava estudando e de quebra ajudar mais pessoas
E por fim, queria deixar uma dica muito legal do Willian Justen para você que precisa de uma ideia de README.md aqui Awesome README você irá encontrar vários examplos, basta escolher o que mais agrada você.
Caso você prefira um template de README.md, fica uma dica muito legal de um gist da PurpleBooth.
Uma dica que não está relacionado a Markdown mais como todos projetos precisam, fica mais como um plus. Caso você precise de um arquivo de licença nesse site irá lhe ajudar nessa tarefa Open Source Initiative